# README

## 聪网是比特币未来价值网络的原生执行层

SAT20 是围绕比特币原生资产形成的协议和开源技术体系。SatoshiNet / 聪网是 SAT20 体系中的开放执行网络，目标不是替代 Bitcoin L1，而是把 Bitcoin L1 的资产事实、用户控制权和最终结算能力，延伸到更快、更低成本、可编程、可自动化的执行环境。

我们的长期判断是：**比特币网络会成为未来价值网络的基础，聪网会成为承接价值网络各种服务、应用和 AI Agent 的核心网络。**

当前“让 BTC 社区建设、拥有并运行自己的金融基础设施”仍然是重要目标，但它更准确地说是阶段性落地路径，而不是终局本身。社区 DEX、DAO、钱包、Indexer、Explorer、节点和 Launchpad，是验证 SAT20 原生扩展路线、形成真实使用、费用流和生态协作的第一批场景。

## 六块递进技术栈

```
Indexer
   ↓
STP
   ↓
SatoshiNet
   ↓
智能合约
   ↓
DKVS / D-Indexer
   ↓
AI Agent Wallet
```

这六块不是并列罗列，而是递进关系：Indexer 提供资产事实，STP 提供跨层控制，SatoshiNet 提供主网执行网络，智能合约提供可编程逻辑，DKVS / D-Indexer 提供分布式数据与索引基础，AI Agent Wallet 则从 SAT20 Wallet 演进为面向 Agent 的授权交互入口。

## 一句话理解 SAT20

```
Bitcoin L1 提供资产来源、UTXO 事实、最终结算和争议边界；
Indexer 提供可查询、可复核的资产事实；
STP 提供跨层资产控制、退出和旧状态惩罚路径；
SatoshiNet 提供交易、资产、区块、合约和应用执行；
智能合约、DKVS / D-Indexer、AI Agent Wallet 让聪网继续走向更开放的价值网络服务层。
```

## 名称与关系

| 名称               | 定位                                                         |
| ---------------- | ---------------------------------------------------------- |
| SAT20            | 围绕比特币原生资产形成的协议和开源技术体系                                      |
| SatoshiNet / 聪网  | 比特币未来价值网络的原生执行层                                            |
| Indexer          | 主网上线的 BTC L1 与聪网资产事实层                                      |
| STP / Transcend  | 主网上线的 BTC L1 与聪网之间的跨层资产控制、退出和惩罚协议                          |
| SatoshiNet       | 主网上线的交易、资产、区块、合约、应用和服务执行网络                                 |
| 智能合约             | 基于 SatoshiNet 的可编程执行层，包括模板合约、EVM Runtime 测试网和未来 Agent 合约方向 |
| DKVS / D-Indexer | 开发中的分布式键值基础设施和分布式 L1 Indexer；DKVS 是 D-Indexer 的底层基础之一      |
| SAT20 Wallet     | 已有浏览器插件和 PWA 两种形式，并持续迭代的钱包入口                               |
| AI Agent Wallet  | 从 SAT20 Wallet 演进而来的 Agent 授权操作入口                          |
| ORDX             | SAT20 体系中的聪本位资产协议                                          |
| GAS              | 聪网原生的网络费用与安全质押资产                                           |

## 为什么需要聪网

Bitcoin L1 适合承担稀缺资产、最终结算和长期安全，但不适合承载所有高频交易、复杂合约、社区治理、AI Agent 操作和大规模应用执行。扩展执行是比特币规模化发展的自然方向，关键问题是：如何在获得更高性能的同时，保留与 Bitcoin L1 资产事实、用户控制权和退出路径的联系。

聪网探索的是一条开放的比特币原生扩展路径：

1. 资产来自 Bitcoin L1。
2. 资产事实可以追溯和复核。
3. 用户保留异常情况下的退出与保护路径。
4. 应用在更快、成本更低、可编程的网络中执行。
5. 社区、开发者和第三方能够独立运行基础设施，而不是永久依赖 SAT20 Labs。
6. AI Agent 可以在不绕过钱包授权、不持有用户私钥的前提下，理解证据、解释风险、生成计划并执行操作。

## 从 Bitcoin 事实到 Agent Wallet

```
Bitcoin L1：资产来源、UTXO 事实、最终结算和争议边界
   ↓
Indexer：主网资产事实层
   ↓
STP：主网跨层控制、退出与惩罚
   ↓
SatoshiNet：主网交易、资产、区块和服务执行
   ↓
智能合约：模板合约、EVM Runtime 测试网、Agent 合约方向
   ↓
DKVS / D-Indexer：分布式数据、状态协作和 L1 资产事实网络
   ↓
AI Agent Wallet：基于 SAT20 Wallet 的授权交互入口
```

## 当前能做什么

| 能力          | 当前用途                                                     | 入口                                                                              |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 理解聪网        | 理解为什么需要比特币原生扩展、资产安全模型、Indexer、STP、智能合约、GAS 和 AI Agent    | [Learn：理解聪网](/learn-li-jie-cong-wang/learn)                                     |
| 社区基础设施      | 为 BTC 社区规划节点、Indexer、Explorer、钱包、DEX、DAO、Launchpad 和运营后台 | [社区技术栈](/sheng-tai-luo-di-lu-jing-she-qu-zi-you-ji-chu-she-shi/community-stack) |
| 资产进入聪网      | 通过主网 Indexer 识别 BTC L1 资产事实，通过主网 STP 将资产纳入用户可退出的通道安全边界   | [STP 简介](/learn-li-jie-cong-wang/stp)                                           |
| 用户使用        | 使用 SAT20 Wallet 插件或 PWA 进入聪网、完成 Swap、使用 Explorer 验证交易    | [使用聪网](/shi-yong-cong-wang/use)                                                 |
| 开发者构建       | 接入 Indexer、STP、SatoshiNet、智能合约、Wallet SDK 和社区 DEX / DAO  | [开发者中心](/kai-fa-zhe-zhong-xin/build)                                            |
| 节点运行        | 运行挖矿节点、核心节点、Indexer、Explorer、RPC 和监控服务                   | [运行网络](/yun-xing-wang-luo-jie-dian-yu-ji-chu-she-shi/run)                       |
| 网络经济        | 理解 GAS、费用流、节点质押、激励和设计中参数                                 | [网络经济](/wang-luo-jing-ji/network-economics)                                     |
| AI Agent 操作 | 让 Agent 在不持有私钥、不绕过钱包授权的前提下执行资产安全检查和操作                    | [AI Agent](/ai-agent-zi-dong-hua-yu-an-quan/ai)                                 |
| 生态合作        | 申请试点、贡献工具、提供流动性、运行节点或支持协议开发                              | [生态建设](/sheng-tai-jian-she/ecosystem)                                           |

## 选择你的角色

| 你是谁                   | 从这里开始                                                           |
| --------------------- | --------------------------------------------------------------- |
| 我运营一个 BTC 社区          | [社区路径](/kai-shi-xuan-ze-ni-de-lu-jing/btc-community)            |
| 我是 Solidity / EVM 开发者 | [开发者路径](/kai-shi-xuan-ze-ni-de-lu-jing/developers)              |
| 我运行基础设施               | [基础设施路径](/kai-shi-xuan-ze-ni-de-lu-jing/infrastructure)         |
| 我是钱包或交易平台             | [钱包与交易平台路径](/kai-shi-xuan-ze-ni-de-lu-jing/wallet-exchange)     |
| 我是 AI Agent 开发者       | [AI Agent 路径](/kai-shi-xuan-ze-ni-de-lu-jing/ai-agent-builders) |
| 我想提供流动性               | [流动性路径](/kai-shi-xuan-ze-ni-de-lu-jing/liquidity)               |

## 安全用证据表达

聪网不采用中心化托管桥作为核心跨层模型。用户保护能力依赖 STP 通道状态、有效承诺交易、惩罚覆盖、钱包备份、Indexer 证据和 BTC L1 可执行路径。

用户、钱包和 Agent 需要能验证：

1. 资产位于 BTC L1、STP 通道、聪网个人地址还是合约地址。
2. 关键交易能追溯到 txid、vout、height 和 confirmations。
3. 钱包持有最新承诺交易和必要备份。
4. 旧状态有惩罚覆盖。
5. Core Node 离线、拒绝服务或作恶时，用户仍有退出或保护路径。
6. 设计中能力不会被伪装成已完成产品。

## 当前关键状态

官网和文档中心使用同一套状态口径表达能力边界：

| 能力                             | 当前状态                    | 说明                                                    |
| ------------------------------ | ----------------------- | ----------------------------------------------------- |
| Indexer                        | Implemented · Mainnet   | 主网上线的 BTC L1 与聪网资产事实层，为资产、交易、确认和协议事件提供可复核状态           |
| STP                            | Implemented · Mainnet   | STP 已开发完成并上线主网，承担跨层资产控制、退出和旧状态惩罚路径                    |
| SatoshiNet                     | Implemented · Mainnet   | 主网执行网络，承载交易、资产表达、基础应用和服务运行                            |
| 智能合约 / EVM Runtime             | Testnet / Iterating     | EVM Runtime 已开发完成并上线测试网，模板合约和合约开发者体验持续迭代              |
| DKVS / D-Indexer               | In Development          | DKVS 和分布式 L1 Indexer 正在开发中，服务未来更开放的节点、索引和 Agent 协作网络  |
| SAT20 Wallet / AI Agent Wallet | Implemented · Iterating | SAT20 Wallet 已有插件和 PWA 两种形式；AI Agent Wallet 在此基础上继续演进 |
| VSN / 长期治理                     | Design / R\&D           | 继续进行设计、实验和验证，不表达为已完成生产能力                              |

## 状态与证据

Docs 使用统一状态表达：

| 状态                      | 含义                               |
| ----------------------- | -------------------------------- |
| 已实现（Implemented）        | 代码与核心流程已经存在，但不自动代表完整生产成熟度        |
| 主网（Mainnet）             | 能力已经部署到主网环境，但仍需要结合文档和风险边界理解生产成熟度 |
| 测试网（Testnet）            | 已有可复现测试网流程                       |
| 开发中（In Development）     | 代码正在推进，尚不承诺完整可用                  |
| 迭代中（Iterating）          | 能力已经存在，但还在持续改进产品体验、接口或安全边界       |
| 设计中（Design in Progress） | 规则、参数或治理尚未定稿                     |
| 研发中（R\&D）               | 研究性基础设施方向，可能继续调整                 |
| 实验性（Experimental）       | 研究性功能，可能改变或取消                    |

每一项状态持续链接到代码、文档、Demo、Explorer、合约地址、测试交易或验证记录。

## 官方入口

* 官网：[sat20.org](https://sat20.org)
* 官方文档：[docs.sat20.org](https://docs.sat20.org)
* X：[SAT20Labs](https://x.com/SAT20Labs)
* GitHub：[sat20-labs](https://github.com/sat20-labs)

这份文档服务用户、开发者、社区、节点运营者、钱包、交易平台、AI Agent、基础设施团队和战略合作伙伴。官网负责愿景、结果、机会和行动路径；Docs 负责协议事实、实现、证据和风险边界。


# 欢迎来到 SAT20

## 聪网是比特币未来价值网络的原生执行层

SAT20 是围绕比特币原生资产形成的协议和开源技术体系。SatoshiNet / 聪网是 SAT20 体系中的开放执行网络，目标不是替代 Bitcoin L1，而是把 Bitcoin L1 的资产事实、用户控制权和最终结算能力，延伸到更快、更低成本、可编程、可自动化的执行环境。

我们的长期判断是：**比特币网络会成为未来价值网络的基础，聪网会成为承接价值网络各种服务、应用和 AI Agent 的核心网络。**

当前“让 BTC 社区建设、拥有并运行自己的金融基础设施”仍然是重要目标，但它更准确地说是阶段性落地路径，而不是终局本身。社区 DEX、DAO、钱包、Indexer、Explorer、节点和 Launchpad，是验证 SAT20 原生扩展路线、形成真实使用、费用流和生态协作的第一批场景。

## 六块递进技术栈

```
Indexer
   ↓
STP
   ↓
SatoshiNet
   ↓
智能合约
   ↓
DKVS / D-Indexer
   ↓
AI Agent Wallet
```

这六块不是并列罗列，而是递进关系：Indexer 提供资产事实，STP 提供跨层控制，SatoshiNet 提供主网执行网络，智能合约提供可编程逻辑，DKVS / D-Indexer 提供分布式数据与索引基础，AI Agent Wallet 则从 SAT20 Wallet 演进为面向 Agent 的授权交互入口。

## 一句话理解 SAT20

```
Bitcoin L1 提供资产来源、UTXO 事实、最终结算和争议边界；
Indexer 提供可查询、可复核的资产事实；
STP 提供跨层资产控制、退出和旧状态惩罚路径；
SatoshiNet 提供交易、资产、区块、合约和应用执行；
智能合约、DKVS / D-Indexer、AI Agent Wallet 让聪网继续走向更开放的价值网络服务层。
```

## 名称与关系

| 名称               | 定位                                                                                                                                                 |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAT20            | 围绕比特币原生资产形成的协议和开源技术体系                                                                                                                              |
| SatoshiNet / 聪网  | 比特币未来价值网络的原生执行层                                                                                                                                    |
| Indexer          | 主网上线的 BTC L1 与聪网资产事实层                                                                                                                              |
| STP / Transcend  | 主网上线的 BTC L1 与聪网之间的跨层资产控制、退出和惩罚协议                                                                                                                  |
| SatoshiNet       | 主网上线的交易、资产、区块、合约、应用和服务执行网络                                                                                                                         |
| 智能合约             | 基于 SatoshiNet 的可编程执行层，框架已完成开发并进入公开测试网；当前测试 Agent / Prediction 合约，以及 PWA `工具 -> 智能合约` 中的模板 AMM / 限价单、EVM `ConstantProductAMM` / `LimitOrderBook` 样本 |
| DKVS / D-Indexer | 开发中的分布式键值基础设施和分布式 L1 Indexer；DKVS 是 D-Indexer 的底层基础之一                                                                                              |
| SAT20 Wallet     | 已有浏览器插件和 PWA 两种形式，并持续迭代的钱包入口                                                                                                                       |
| AI Agent Wallet  | 从 SAT20 Wallet 演进而来的 Agent 授权操作入口                                                                                                                  |
| ORDX             | SAT20 体系中的聪本位资产协议                                                                                                                                  |
| GAS              | 聪网原生的网络费用与安全质押资产                                                                                                                                   |

## 为什么需要聪网

Bitcoin L1 适合承担稀缺资产、最终结算和长期安全，但不适合承载所有高频交易、复杂合约、社区治理、AI Agent 操作和大规模应用执行。扩展执行是比特币规模化发展的自然方向，关键问题是：如何在获得更高性能的同时，保留与 Bitcoin L1 资产事实、用户控制权和退出路径的联系。

聪网探索的是一条开放的比特币原生扩展路径：

1. 资产来自 Bitcoin L1。
2. 资产事实可以追溯和复核。
3. 用户保留异常情况下的退出与保护路径。
4. 应用在更快、成本更低、可编程的网络中执行。
5. 社区、开发者和第三方能够独立运行基础设施，而不是永久依赖 SAT20 Labs。
6. AI Agent 可以在不绕过钱包授权、不持有用户私钥的前提下，理解证据、解释风险、生成计划并执行操作。

## 从 Bitcoin 事实到 Agent Wallet

```
Bitcoin L1：资产来源、UTXO 事实、最终结算和争议边界
   ↓
Indexer：主网资产事实层
   ↓
STP：主网跨层控制、退出与惩罚
   ↓
SatoshiNet：主网交易、资产、区块和服务执行
   ↓
智能合约：已进入公开测试网的 Agent / Prediction 合约，以及 PWA 工具中的模板 AMM / 限价单、EVM ConstantProductAMM / LimitOrderBook
   ↓
DKVS / D-Indexer：分布式数据、状态协作和 L1 资产事实网络
   ↓
AI Agent Wallet：基于 SAT20 Wallet 的授权交互入口
```

## 当前能做什么

| 能力          | 当前用途                                                     | 入口                                                                              |
| ----------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| 理解聪网        | 理解为什么需要比特币原生扩展、资产安全模型、Indexer、STP、智能合约、GAS 和 AI Agent    | [Learn：理解聪网](/learn-li-jie-cong-wang/learn)                                     |
| 社区基础设施      | 为 BTC 社区规划节点、Indexer、Explorer、钱包、DEX、DAO、Launchpad 和运营后台 | [社区技术栈](/sheng-tai-luo-di-lu-jing-she-qu-zi-you-ji-chu-she-shi/community-stack) |
| 资产进入聪网      | 通过主网 Indexer 识别 BTC L1 资产事实，通过主网 STP 将资产纳入用户可退出的通道安全边界   | [STP 简介](/learn-li-jie-cong-wang/stp)                                           |
| 用户使用        | 使用 SAT20 Wallet 插件或 PWA 进入聪网、完成 Swap、使用 Explorer 验证交易    | [使用聪网](/shi-yong-cong-wang/use)                                                 |
| 测试智能合约      | 使用 PWA Wallet 领取测试 GAS、部署或参与 Prediction 合约测试             | [Prediction 合约测试](/shi-yong-cong-wang/prediction-contract)                      |
| 开发者构建       | 接入 Indexer、STP、SatoshiNet、智能合约、Wallet SDK 和社区 DEX / DAO  | [开发者中心](/kai-fa-zhe-zhong-xin/build)                                            |
| 节点运行        | 运行挖矿节点、核心节点、Indexer、Explorer、RPC 和监控服务                   | [运行网络](/yun-xing-wang-luo-jie-dian-yu-ji-chu-she-shi/run)                       |
| 网络经济        | 理解 GAS、费用流、节点质押、激励和设计中参数                                 | [网络经济](/wang-luo-jing-ji/network-economics)                                     |
| AI Agent 操作 | 让 Agent 在不持有私钥、不绕过钱包授权的前提下执行资产安全检查和操作                    | [AI Agent](/ai-agent-zi-dong-hua-yu-an-quan/ai)                                 |
| 生态合作        | 申请试点、贡献工具、提供流动性、运行节点或支持协议开发                              | [生态建设](/sheng-tai-jian-she/ecosystem)                                           |

## 选择你的角色

| 你是谁                   | 从这里开始                                                           |
| --------------------- | --------------------------------------------------------------- |
| 我运营一个 BTC 社区          | [社区路径](/kai-shi-xuan-ze-ni-de-lu-jing/btc-community)            |
| 我是 Solidity / EVM 开发者 | [开发者路径](/kai-shi-xuan-ze-ni-de-lu-jing/developers)              |
| 我运行基础设施               | [基础设施路径](/kai-shi-xuan-ze-ni-de-lu-jing/infrastructure)         |
| 我是钱包或交易平台             | [钱包与交易平台路径](/kai-shi-xuan-ze-ni-de-lu-jing/wallet-exchange)     |
| 我是 AI Agent 开发者       | [AI Agent 路径](/kai-shi-xuan-ze-ni-de-lu-jing/ai-agent-builders) |
| 我想提供流动性               | [流动性路径](/kai-shi-xuan-ze-ni-de-lu-jing/liquidity)               |

## 安全用证据表达

聪网不采用中心化托管桥作为核心跨层模型。用户保护能力依赖 STP 通道状态、有效承诺交易、惩罚覆盖、钱包备份、Indexer 证据和 BTC L1 可执行路径。

用户、钱包和 Agent 需要能验证：

1. 资产位于 BTC L1、STP 通道、聪网个人地址还是合约地址。
2. 关键交易能追溯到 txid、vout、height 和 confirmations。
3. 钱包持有最新承诺交易和必要备份。
4. 旧状态有惩罚覆盖。
5. Core Node 离线、拒绝服务或作恶时，用户仍有退出或保护路径。
6. 设计中能力不会被伪装成已完成产品。

## 当前关键状态

官网和文档中心使用同一套状态口径表达能力边界：

| 能力                             | 当前状态                    | 说明                                                                                                                               |
| ------------------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Indexer                        | Implemented · Mainnet   | 主网上线的 BTC L1 与聪网资产事实层，为资产、交易、确认和协议事件提供可复核状态                                                                                      |
| STP                            | Implemented · Mainnet   | STP 已开发完成并上线主网，承担跨层资产控制、退出和旧状态惩罚路径                                                                                               |
| SatoshiNet                     | Implemented · Mainnet   | 主网执行网络，承载交易、资产表达、基础应用和服务运行                                                                                                       |
| 智能合约 / EVM Runtime / Agent 合约  | Testnet / Iterating     | 智能合约框架已完成开发并进入公开测试网；当前验证 Agent / Prediction 合约，以及 PWA `工具 -> 智能合约` 中的模板 AMM / 限价单、EVM `ConstantProductAMM` / `LimitOrderBook` 样本 |
| DKVS / D-Indexer               | In Development          | DKVS 和分布式 L1 Indexer 正在开发中，服务未来更开放的节点、索引和 Agent 协作网络                                                                             |
| SAT20 Wallet / AI Agent Wallet | Implemented · Iterating | SAT20 Wallet 已有插件和 PWA 两种形式；AI Agent Wallet 在此基础上继续演进                                                                            |
| VSN / 长期治理                     | Design / R\&D           | 继续进行设计、实验和验证，不表达为已完成生产能力                                                                                                         |

## 状态与证据

Docs 使用统一状态表达：

| 状态                      | 含义                               |
| ----------------------- | -------------------------------- |
| 已实现（Implemented）        | 代码与核心流程已经存在，但不自动代表完整生产成熟度        |
| 主网（Mainnet）             | 能力已经部署到主网环境，但仍需要结合文档和风险边界理解生产成熟度 |
| 测试网（Testnet）            | 已有可复现测试网流程                       |
| 开发中（In Development）     | 代码正在推进，尚不承诺完整可用                  |
| 迭代中（Iterating）          | 能力已经存在，但还在持续改进产品体验、接口或安全边界       |
| 设计中（Design in Progress） | 规则、参数或治理尚未定稿                     |
| 研发中（R\&D）               | 研究性基础设施方向，可能继续调整                 |
| 实验性（Experimental）       | 研究性功能，可能改变或取消                    |

每一项状态持续链接到代码、文档、Demo、Explorer、合约地址、测试交易或验证记录。

## 官方入口

* 官网：[sat20.org](https://sat20.org)
* 官方文档：[docs.sat20.org](https://docs.sat20.org)
* X：[SAT20Labs](https://x.com/SAT20Labs)
* GitHub：[sat20-labs](https://github.com/sat20-labs)

这份文档服务用户、开发者、社区、节点运营者、钱包、交易平台、AI Agent、基础设施团队和战略合作伙伴。官网负责愿景、结果、机会和行动路径；Docs 负责协议事实、实现、证据和风险边界。


# 开始：选择你的路径


# 概述

聪网文档的第一目标不是让读者先读完所有协议，而是让每一类建设者在几分钟内知道：聪网能为我解决什么问题，现在有哪些能力可以用，我可以建设什么，下一步点击哪里。

如果你还不确定从哪里开始，先选择你的角色。

## 角色入口

| 你是谁                      | 你最关心的问题                    | 推荐入口                                                                |
| ------------------------ | -------------------------- | ------------------------------------------------------------------- |
| BTC 资产或社区负责人             | 如何为社区搭建自己的 DEX、DAO、钱包和基础设施 | [我运营一个 BTC 社区](/kai-shi-xuan-ze-ni-de-lu-jing/btc-community)        |
| Solidity / EVM 开发者       | 如何在聪网上部署第一个合约              | [我是开发者](/kai-shi-xuan-ze-ni-de-lu-jing/developers)                  |
| 节点、Indexer 或 Explorer 团队 | 如何运行基础设施并提供公共服务            | [我运行基础设施](/kai-shi-xuan-ze-ni-de-lu-jing/infrastructure)            |
| 钱包或交易平台                  | 如何接入资产查询、充值提现、STP 和钱包授权    | [我是钱包或交易平台](/kai-shi-xuan-ze-ni-de-lu-jing/wallet-exchange)         |
| AI Agent 开发者             | 如何让 Agent 安全操作钱包、合约和社区部署流程 | [我是 AI Agent 开发者](/kai-shi-xuan-ze-ni-de-lu-jing/ai-agent-builders) |
| 做市商或流动性合作方               | 如何参与 AMM、限价单和跨社区流动性        | [我想提供流动性](/kai-shi-xuan-ze-ni-de-lu-jing/liquidity)                 |

## 三分钟判断

进入聪网生态前，先回答四个问题：

1. 你要服务的是用户资产流动、社区治理、合约应用、基础设施，还是 AI Agent 自动化？
2. 你需要的资产事实来自 BTC L1、聪网 L2，还是两者之间的跨层证据？
3. 你的用户是否需要自己掌控资产退出路径？
4. 你希望先完成测试网验证、公开展示、还是直接申请合作？

如果目标是为一个 BTC 社区搭建完整基础设施，优先阅读 [Community Stack](/sheng-tai-luo-di-lu-jing-she-qu-zi-you-ji-chu-she-shi/community-stack)。

如果目标是先看聪网当前已经具备哪些能力，阅读 [SatoshiNet Today：当前可用能力](/sheng-tai-jian-she/satoshinet-today)。

如果目标是提交合作或进入生态支持流程，阅读 [Builder Program](/sheng-tai-jian-she/builder-program)。


# 我运营一个 BTC 社区

如果你运营一个 BTC 资产社区、铭文社区、Runes / BRC20 / ORDX 社区，聪网的目标是帮助你搭建并逐步自主运营自己的金融基础设施。

你不需要一开始就理解所有 STP、Indexer 或合约细节。你需要先确定：社区希望拥有哪些能力。

## 你可以建设什么

一个社区可以逐步拥有：

1. 自己的聪网核心节点。
2. 自己的 L1 / L2 Indexer。
3. 自己的 Explorer。
4. 自己的钱包入口或 Wallet SDK 集成。
5. 自己的 Launchpad。
6. 自己的 AMM 池。
7. 自己的限价单市场。
8. 自己的 DAO 和社区基金管理流程。
9. 自己的 DEX 前端与后台。
10. 自己的品牌、域名、资产规则和运营规则。

## 你需要准备什么

| 事项     | 说明                                          |
| ------ | ------------------------------------------- |
| 社区目标   | 是做交易、治理、Launchpad、流动性，还是完整 DEX / DAO        |
| 资产信息   | 资产协议、ticker、供应、持有人、当前流动性                    |
| 运营主体   | 谁负责社区运营、用户支持、内容和公告                          |
| 签名与治理  | 谁能签署关键操作，如何做多签或 DAO 决策                      |
| 流动性计划  | 是否需要 AMM 初始池、限价单市场、做市伙伴                     |
| 基础设施能力 | 是否自己运行节点、Indexer、Explorer，或先由 SAT20 Labs 协助 |

## 推荐流程

1. 阅读 [Community Stack](/sheng-tai-luo-di-lu-jing-she-qu-zi-you-ji-chu-she-shi/community-stack)，选择需要的模块。
2. 查看 [SatoshiNet Today](/sheng-tai-jian-she/satoshinet-today)，确认当前可用能力。
3. 准备社区需求说明：资产、目标、用户、流动性、治理和上线时间。
4. 通过 [Builder Program](/sheng-tai-jian-she/builder-program) 提交合作意向。
5. 先在测试网部署社区 DEX / DAO 原型。
6. 用 Explorer、Indexer 和钱包验证资产、交易和合约状态。
7. 完成公开说明、用户教程和风险提示。

## 成功标准

一个社区试点至少应能证明：

1. 用户能安装钱包并看到资产。
2. 社区资产能被 Indexer 正确识别。
3. 用户能通过 DEX 或合约完成一次真实测试网操作。
4. Explorer 能展示相关交易或合约状态。
5. 社区能说明用户如何退出、如何验证资产状态、遇到问题如何恢复。


# 我是开发者

开发者可以从三个方向进入聪网：

1. 构建智能合约和应用。
2. 接入钱包、Indexer、STP 和交易平台。
3. 帮社区搭建 DEX、DAO、Launchpad 或 AI Agent 工具。

## 推荐路径

| 目标                       | 下一步                                                                              |
| ------------------------ | -------------------------------------------------------------------------------- |
| 理解 EVM 开发者预览             | [EVM 开发者预览](/kai-fa-zhe-zhong-xin/evm-quickstart)                                |
| 查看 EVM 样本合约              | [EVM 样本合约](/kai-fa-zhe-zhong-xin/evm-sample-contracts)                           |
| 测试 Prediction / Agent 合约 | [Prediction 合约 Quickstart](/kai-fa-zhe-zhong-xin/prediction-contract-quickstart) |
| 构建社区 DEX / DAO           | [社区 DEX / DAO Quickstart](/kai-fa-zhe-zhong-xin/community-dex-quickstart)        |
| 接入资产数据                   | [Indexer 接入与资产事实层](/kai-fa-zhe-zhong-xin/indexer)                                |
| 实现 STP 客户端               | [第三方 STP 客户端接入指南](/xie-yi-yu-an-quan/stp/client-integration)                     |
| 集成钱包                     | [交易平台与钱包接入](/kai-fa-zhe-zhong-xin/exchange-and-wallet)                           |
| 构建 AI Agent              | [SatoshiNet AI Agent Quickstart](/kai-fa-zhe-zhong-xin/ai-agent-quickstart)      |

## 开发者需要理解的基础

1. BTC L1 是资产来源。
2. Indexer 是资产事实层。
3. STP 是跨层资产安全边界。
4. SatoshiNet 是低成本执行环境。
5. 智能合约和 GAS 让聪网成为应用网络。
6. 钱包和 Agent 负责把复杂协议变成用户可操作流程。

## 当前最需要的开发者

1. EVM 工具链与 Solidity 迁移开发者。
2. AMM、限价单、Launchpad、DAO 模板开发者。
3. 钱包和交易平台集成开发者。
4. Indexer、Explorer、RPC、监控和数据服务开发者。
5. AI Agent adapter、部署助手和安全验证助手开发者。


# 我运行基础设施

聪网需要基础设施团队参与运行 Core Node、Indexer、Explorer、RPC、监控和数据服务。

基础设施不是边缘角色。Indexer 和节点共同决定用户能否验证资产事实、交易状态、合约状态和跨层证据。

## 可参与方向

| 方向         | 价值                                           |
| ---------- | -------------------------------------------- |
| Core Node  | 提供 STP 服务、SatoshiNet 节点能力和网络基础服务             |
| L1 Indexer | 解析 BTC L1 上的 Ordinals、Runes、BRC20、ORDX 等资产事实 |
| L2 Indexer | 索引 SatoshiNet UTXO、ascend、descend、通道、合约和交易状态 |
| Explorer   | 为用户、社区和交易平台提供可视化验证入口                         |
| RPC / API  | 为钱包、DEX、Agent、交易平台和开发者提供稳定访问                 |
| 监控与告警      | 保障节点、Indexer、STP、合约和 API 长期运行                |

## 推荐路径

1. 阅读 [SatoshiNet 协议概览](/xie-yi-yu-an-quan/satoshinet/satoshinet)。
2. 阅读 [Indexer：比特币资产事实层](/learn-li-jie-cong-wang/indexer)。
3. 阅读 [运行基础设施 Quickstart](/kai-fa-zhe-zhong-xin/infrastructure-quickstart)。
4. 在测试网运行一个节点或 Indexer。
5. 为钱包或社区项目提供只读 API。
6. 通过 Explorer 或监控面板公开运行状态。

## 关键原则

1. 单个服务返回不是最终事实，关键状态需要链上证据和跨源验证。
2. L1/L2 高度、reorg、mempool、未索引状态必须清晰表达。
3. 面向钱包和交易平台的 API 需要稳定错误码和下一步建议。
4. 运行者不应替用户保管私钥或绕过钱包授权。


# 我是钱包或交易平台

钱包和交易平台是聪网生态的重要入口。用户最终需要在钱包和交易平台中完成资产识别、充值提现、跨层流动、交易和安全验证。

## 你需要接入什么

| 能力          | 作用                                           |
| ----------- | -------------------------------------------- |
| L1 Indexer  | 查询 BTC L1 UTXO、资产、确认数和花费状态                   |
| L2 Indexer  | 查询聪网 UTXO、交易、合约、通道和跨层状态                      |
| STP 状态      | 判断通道、splicing、unlock、lock、close 和 pending 事务 |
| 钱包授权        | 用户签名、交易确认、助记词和密码留在钱包安全边界内                    |
| Explorer 链接 | 给用户和客服提供可复核证据                                |

## 推荐路径

1. 阅读 [交易平台与钱包接入](/kai-fa-zhe-zhong-xin/exchange-and-wallet)。
2. 阅读 [API 源码地图](/kai-fa-zhe-zhong-xin/api-source-map)，定位当前权威接口实现。
3. 阅读 [Indexer 接入与资产事实层](/kai-fa-zhe-zhong-xin/indexer)。
4. 如果需要跨层资产流动，阅读 [第三方 STP 客户端接入指南](/xie-yi-yu-an-quan/stp/client-integration)。
5. 在测试网上完成充值、提现、splicing-in、splicing-out、unlock、lock 的证据链验证。

## 上线前检查

1. 是否能区分 L1 余额、L2 可花费余额和 pending 状态。
2. 是否能处理 timeout / EOF / 未索引 / reorg 等未知结果。
3. 是否能展示 txid、vout、height、confirmations 和 explorer 链接。
4. 是否能阻止用户在通道安全证据缺失时继续价值移动。
5. 是否能在主网操作前展示清晰授权信息。


# 我是 AI Agent 开发者

AI Agent 在聪网生态中有两条产品线。

第一条是 Agent Wallet & Safety：帮助用户安全操作钱包、STP 通道和资产跨层流动。

第二条是 Community Builder Agent：帮助 BTC 社区通过对话设计并逐步部署自己的 DEX、DAO、Indexer、Explorer、钱包入口和合约模块。

## Agent Wallet & Safety

这条路径已经有较完整的安全基础：

1. Agent 不保存私钥、助记词或钱包密码。
2. Agent 通过 PWA Wallet adapter 调用钱包。
3. Agent 在价值移动前读取 `stp.safety_snapshot`。
4. Agent 检查 commitment、punish coverage、L1/L2 indexer 证据和 pending 事务。
5. Agent 在未知网络结果、缺少惩罚覆盖或通道降级时停止操作。

入口：

* [SAT20 Agent Wallet 安装与使用](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/sat20-agent-wallet)
* [资产安全控制指南](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/asset-safety)
* [验证矩阵与数据缺口](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/verification-and-data-gaps)

## Community Builder Agent

这条路径是后续生态建设重点。目标是：

> 让任何 BTC 社区通过几轮对话，设计并逐步部署自己的 DAO、DEX、钱包、Indexer 和 Explorer。

它需要文档和工具逐步具备：

1. 每个模块有明确输入和输出。
2. 参数能用 JSON Schema 表达。
3. API 和错误码稳定。
4. 配置示例可复制。
5. 合约模板有机器可读描述。
6. 部署步骤能对应具体工具调用。
7. 每一步都需要钱包签名确认和链上证据。

## 推荐路径

1. 从 [SatoshiNet AI Agent Quickstart](/kai-fa-zhe-zhong-xin/ai-agent-quickstart) 开始。
2. 使用 [Community Stack](/sheng-tai-luo-di-lu-jing-she-qu-zi-you-ji-chu-she-shi/community-stack) 理解社区完整方案。
3. 将每个模块的用户输入、配置输出、部署结果和验证证据结构化。
4. 优先在测试网完成只读查询、配置生成和人工确认部署。


# 我想提供流动性

做市商和流动性合作方可以帮助聪网资产形成真实交易深度。

流动性参与不只是提供资金，还包括资产定价、交易路径、AMM 池、限价单市场、跨社区协作和风险控制。

## 可参与方向

| 方向        | 说明                   |
| --------- | -------------------- |
| AMM 池     | 为社区资产和基础资产提供自动做市     |
| 限价单市场     | 为专业用户和做市策略提供订单簿      |
| Launchpad | 帮助新资产完成初始发行和流动性启动    |
| 跨社区流动性    | 连接不同 BTC 资产社区的交易和资金  |
| 风险工具      | 监控价格、深度、滑点、异常交易和合约状态 |

## 推荐路径

1. 阅读 [Built on SatoshiNet](/sheng-tai-jian-she/built-on-satoshinet)，查看已有模块。
2. 阅读 [SatoshiNet Today](/sheng-tai-jian-she/satoshinet-today)，确认 AMM、限价单、Launchpad 等状态。
3. 如果你为某个社区服务，先阅读 [我运营一个 BTC 社区](/kai-shi-xuan-ze-ni-de-lu-jing/btc-community)。
4. 通过 [Builder Program](/sheng-tai-jian-she/builder-program) 提交流动性合作意向。

## 风险边界

1. Docs 不承诺收益，不提供投资建议。
2. 任何 AMM 或限价单策略都需要独立评估资产风险和流动性风险。
3. 主网资金操作必须由钱包或多签授权。
4. 所有交易和合约状态应能通过 Explorer、Indexer 或链上交易验证。


# 生态落地路径：社区自有基础设施


# 为你的 BTC 社区搭建完整基础设施

Community Stack 是聪网面向 BTC 社区的完整基础设施方案。它的目标不是让社区只把资产“桥接”到另一个网络，而是帮助社区逐步拥有自己的 DEX、DAO、钱包入口、Indexer、Explorer、Launchpad、AMM、限价单系统和运营后台。

一句话目标：

> 让每一个 BTC 社区拥有自己的金融基础设施。

## 社区最终可以拥有

| 模块                  | 作用                               |
| ------------------- | -------------------------------- |
| Core Node           | 提供 SatoshiNet 节点、STP 服务和社区基础服务能力 |
| L1 / L2 Indexer     | 统一表达 BTC L1 与聪网 L2 的资产事实         |
| Explorer            | 向用户展示交易、资产、合约、通道和跨层证据            |
| Wallet / Wallet SDK | 让用户持有资产、签名、授权和验证状态               |
| Launchpad           | 支持社区资产发行、活动和初始分发                 |
| AMM                 | 支持自动做市和基础流动性                     |
| 限价单系统               | 支持订单簿交易和专业做市                     |
| Transcend / STP     | 支持 BTC L1 资产进入和退出聪网              |
| DAO                 | 支持社区治理、参数管理和社区基金流程               |
| DEX 前端与后台           | 支持社区自己的交易入口和运营管理                 |
| AI Agent            | 支持需求分析、部署配置、安全检查和运营报告            |

## 社区负责什么

1. 品牌、域名和社区运营。
2. 资产规则、活动规则和市场规则。
3. 流动性和做市策略。
4. DAO 参数、签名人、治理流程和社区基金决策。
5. 用户支持、公告和风险提示。
6. 最终链上签名和治理决策。

## SAT20 Labs 提供什么

| 支持                      | 内容                                     |
| ----------------------- | -------------------------------------- |
| 开源代码                    | 节点、Indexer、钱包、SDK、合约、DEX 和工具链          |
| 合约模板                    | AMM、限价单、DAO、Launchpad 等可复用模块           |
| Wallet SDK              | 钱包、签名、资产查询、PWA adapter 和 Agent adapter |
| Indexer / Explorer      | L1/L2 资产事实、交易、通道和合约状态查询                |
| 部署指南                    | 节点、Indexer、Explorer、DEX、DAO 和合约部署路径    |
| 测试网环境                   | 用于验证资产、合约、交易和用户流程                      |
| 技术接入支持                  | 帮助社区完成测试网试点和上线前验证                      |
| Community Builder Agent | 后续用于生成架构、配置、部署计划和运营报告                  |

## 推荐部署流程

1. 提交社区需求。
2. 选择所需模块：DEX、DAO、Indexer、Explorer、钱包、Launchpad、AMM、限价单等。
3. 生成整体架构和配置。
4. 在测试网完成部署。
5. 完成钱包、Indexer、Explorer 和合约验证。
6. 完成用户教程、风险提示和运营后台配置。
7. 上线社区 DEX / DAO。
8. 进入 [Built on SatoshiNet](/sheng-tai-jian-she/built-on-satoshinet) 展示页。

## 部署模式

| 模式   | 内容                             | 当前状态 |
| ---- | ------------------------------ | ---- |
| 开源自建 | 社区按开源文档自行部署代码、节点和服务            | 规划中  |
| 协助部署 | SAT20 Labs 或生态服务方提供架构、部署、集成和培训 | 规划中  |
| 托管运维 | 节点、Indexer、Explorer、监控与升级服务    | 规划中  |
| 战略共建 | 深度定制、联合测试、流动性与生态合作             | 规划中  |

SAT20 Labs 的目标不是让所有社区依赖我们，而是让每个社区拥有独立运行自己基础设施的能力。

## 社区需求表

提交社区合作需求时，建议包含：

1. 社区名称与联系人。
2. 官网、X、Telegram / Discord。
3. 资产协议、ticker、持有人和当前流动性。
4. 需要的模块：节点、Indexer、Explorer、钱包、DEX、DAO、Launchpad、AMM、限价单、Agent。
5. 是否自行运行节点、Indexer 和 Explorer。
6. 流动性计划。
7. DAO 与签名规则。
8. 测试网上线目标。
9. 预算或资源投入能力。
10. 希望 SAT20 Labs 提供什么。

## 第一次合作建议

首批社区合作可以从最小闭环开始：

1. 一个社区资产。
2. 一个测试网 DEX 页面。
3. 一个 AMM 池或限价单市场。
4. 一个 Explorer 证据入口。
5. 一个钱包安装和交易教程。
6. 一个 DAO 或社区基金的最小治理流程。

## 下一步

* 查看 [SatoshiNet Today：当前可用能力](/sheng-tai-jian-she/satoshinet-today)。
* 阅读 [Builder Program](/sheng-tai-jian-she/builder-program)。
* 准备社区需求说明。
* 申请成为首批社区合作伙伴。

**页面状态：规划中（Planning）**


# Learn：理解聪网


# 概述

Learn 部分面向第一次了解 SAT20 和聪网的读者。这里不要求读者先理解 STP、RSMC、UTXO 或智能合约实现细节，而是先建立几个基本概念。

聪网的目标是成为比特币原生扩展网络。它服务的不是一种单独资产，而是 BTC 主网上的原生资产：BTC、Ordinals、Runes、BRC20、ORDX，以及未来更多基于 UTXO 的资产协议。

## 阅读顺序

1. [为什么需要比特币原生扩展网络](/learn-li-jie-cong-wang/bitcoin-native)
2. [资产安全模型](/learn-li-jie-cong-wang/security-model)
3. [Indexer：比特币资产事实层](/learn-li-jie-cong-wang/indexer)
4. [STP 简介](/learn-li-jie-cong-wang/stp)
5. [智能合约与 GAS](/learn-li-jie-cong-wang/smart-contracts-and-gas)
6. [AI Agent 与用户资产控制](/learn-li-jie-cong-wang/ai-agent)

## 核心概念

| 概念        | 简述                                   |
| --------- | ------------------------------------ |
| 比特币原生扩展网络 | 资产来自 BTC L1，退出和安全边界仍能回到 BTC L1       |
| Indexer   | 将 BTC L1 上不同协议的资产状态统一表达为可查询、可验证的资产事实 |
| STP       | 让资产进入、退出和重新纳入通道保护的协议                 |
| 承诺交易      | 用户在异常情况下可以用来退出的预签名交易                 |
| 惩罚交易      | 当对方广播旧状态时，用来保护用户资产的交易                |
| 智能合约      | 在聪网上运行的应用逻辑                          |
| GAS       | 支付合约执行和网络资源消耗的资产                     |
| AI Agent  | 可以帮助用户理解、验证并执行复杂链上操作的自动化助手           |

## 读完后可以理解什么

读完 Learn 部分后，读者可以回答：

1. 聪网为什么不是普通托管桥。
2. Indexer 为什么是 STP、钱包、交易平台和 Agent 的资产事实层。
3. STP 如何让用户保留资产控制权。
4. 智能合约为什么会改变聪网的应用边界。
5. GAS 为什么是聪网生态的重要经济入口。
6. AI Agent 为什么适合参与 STP 和钱包操作。


# 为什么需要比特币原生扩展网络

比特币主网安全、稳定、全球可验证，但它不是为高频交易、复杂合约和低成本应用交互设计的。随着 Ordinals、Runes、BRC20、ORDX 等资产协议出现，比特币生态需要一个新的流动环境：既能继承 BTC L1 的资产安全，又能支持更快、更便宜、更可编程的应用。

这就是聪网的定位。

## 原生性的含义

“比特币原生”不是一句宣传语。它至少包含四个要求：

1. 资产来源于 BTC L1。
2. 资产状态能被 BTC L1 交易、UTXO 和索引器验证。
3. 用户在异常情况下仍能回到 BTC L1 的退出路径。
4. 网络设计尊重比特币的 UTXO、签名、时间锁和可验证交易模型。

如果一个网络只是在链外记录余额，或把资产托管给中心化桥，再发行一份映射资产，它就不是聪网要追求的模型。

## 聪网的路径

聪网通过 STP 把 BTC L1 资产纳入通道地址，并在聪网上形成可流通状态。用户进入聪网后，可以在更快的环境中转账、交易、使用智能合约；当用户要退出时，可以通过 splicing-out、close 或 force close 回到 BTC L1。

安全性来自协议结构，而不是来自 Core Node 承诺。

## 与其他路径的区别

| 路径          | 优点                               | 主要问题                   |
| ----------- | -------------------------------- | ---------------------- |
| BTC L1 直接交易 | 安全、最终性强                          | 慢、贵、不适合复杂应用            |
| 中心化托管桥      | 使用简单                             | 用户失去资产控制权              |
| 侧链或独立链      | 可编程性强                            | 资产安全依赖外部共识或桥           |
| 闪电网络        | 支付场景成熟                           | 对多资产、合约和应用扩展有限         |
| 聪网          | 面向 BTC 原生资产、STP 安全退出、支持合约和 Agent | 需要更完整的钱包、Indexer、开发者生态 |

聪网不是要替代比特币主网。它的目标是让比特币主网上的资产获得新的流动性和应用空间。


# 资产安全模型

聪网的安全目标是让用户始终知道自己的资产在哪里，以及在 Core Node 离线、失败或作恶时如何取回资产。

这个目标主要由 STP 完成。

## 安全不是余额显示

钱包显示余额不等于资产安全。对 STP 通道来说，Agent 或客户端需要验证以下证据：

1. BTC L1 channel point 是否存在。
2. 最新承诺交易是否可用。
3. 承诺高度是否单调前进。
4. 用户余额和 Core Node 余额是否与承诺状态一致。
5. 已撤销的旧状态是否有惩罚交易覆盖。
6. 强制关闭和 CSV 后清扫路径是否可构造。

如果这些证据缺失，客户端应停止普通价值移动，而不是只相信 Core Node 状态。

## 三种退出能力

| 能力    | 作用                      |
| ----- | ----------------------- |
| 协商关闭  | 双方在线时，按最新状态友好关闭通道       |
| 强制关闭  | peer 不在线时，用户用最新承诺交易退出   |
| 惩罚旧状态 | peer 广播旧承诺交易时，用户用撤销材料惩罚 |

这套机制与闪电网络的 RSMC 思想一致。STP 将它扩展到更多 BTC 原生资产和聪网跨层状态。

## Agent 的角色

AI Agent 不应替用户保管私钥。Agent 应做的是：

1. 调用钱包 adapter。
2. 检查安全快照。
3. 读取承诺交易和惩罚覆盖。
4. 判断是否可以执行 unlock、lock、splicing、close。
5. 向用户解释风险和下一步。

真正的签名、私钥、助记词、通道数据库应留在钱包安全边界内，推荐由 SAT20 PWA Wallet 管理。


# Indexer：比特币资产事实层

比特币主网原生只理解 UTXO 和 BTC。Ordinals、Runes、BRC20、ORDX 等资产协议都建立在 BTC 交易、脚本、铭文、sat range 或协议事件之上。用户、钱包、交易平台、STP 客户端和 AI Agent 要安全操作这些资产，首先需要一个统一的资产事实层。

Indexer 的作用就是把 BTC L1 上的交易事实解析为资产事实：

1. 某个地址有哪些 UTXO。
2. 每个 UTXO 中包含哪些 BTC、Ordinals、Runes、BRC20、ORDX 或其他资产。
3. 这些资产是否确认，是否可能受 mempool、reorg 或协议规则影响。
4. 某个资产转移、铸造、铭刻、部署或销毁事件是否有效。
5. 某个 L1 交易与聪网中的 ascend / descend / 通道状态是否对应。

## 为什么聪网需要 Indexer

STP 负责把 BTC L1 资产纳入通道，并让用户保持退出能力。Indexer 负责告诉钱包和 Agent：这些 BTC L1 资产到底是什么、在哪里、是否已经确认、是否可以进入通道。

没有 indexer，STP 无法可靠回答以下问题：

1. 用户选择的 UTXO 是否真的携带目标资产。
2. BRC20 transfer UTXO 是否有效。
3. Runes、ORDX、Ordinals 的资产归属是否与用户看到的一致。
4. splicing-in 的 L1 交易是否已经确认并可以映射到聪网。
5. splicing-out 或 close 之后，L1 资产是否已经回到用户可控制地址。

因此，聪网的资产基础不是单独的 STP，而是 STP + indexer。STP 提供跨层控制权，indexer 提供资产事实和可验证状态。

## Indexer 不控制资产

Indexer 不是托管方，也不是资产安全的单点信任来源。它的职责是从公开链上数据中计算资产状态，并把结果提供给钱包、交易平台、浏览器、STP 客户端和 Agent。

一个合格的 indexer 应满足三个要求：

1. 可复算：结果来自 BTC L1 和聪网交易，第三方可以独立运行同样规则复核。
2. 可追溯：余额和资产归属应能追溯到具体 txid、vout、sat range、inscription、rune event 或协议事件。
3. 可处理异常：mempool、确认数、reorg、旧状态、无效 transfer 和协议边界都应明确表达。

## L1 Indexer 与 L2 Indexer

聪网生态需要两类索引能力：

| Indexer               | 作用                                                              |
| --------------------- | --------------------------------------------------------------- |
| BTC L1 Indexer        | 解析 BTC 主网上的 UTXO、sat range、Ordinals、Runes、BRC20、ORDX 和普通 BTC 资产 |
| SatoshiNet L2 Indexer | 解析聪网上的 UTXO、ascend、descend、通道、合约、交易执行和资产状态                      |

钱包、交易平台和 Agent 需要把 L1 与 L2 的证据串起来，而不是只看一个余额字段：资产从哪个 BTC UTXO 进入通道，哪个 ascend 事件把它映射到聪网，当前在聪网哪个地址或通道中，退出时又对应哪个 descend / L1 输出。

## 面向未来的分布式 Indexer

SAT20 indexer 不是一个中心化 API 服务，而是一套可独立运行、可交叉验证的资产事实计算规则。

在聪网中，L2 indexer 已经集成在聪网节点中。每个运行聪网节点的参与者都可以随节点维护自己的 L2 交易、UTXO、ascend、descend、通道和合约状态视图。因此，L2 indexer 本质上已经随聪网节点网络分布。

L1 indexer 的数据来源是 BTC 主网。聪网 Core Node 在运行时要求配置并依赖自己的 L1 indexer，用来验证 BTC L1 UTXO、资产协议事件、确认状态和跨层交易。因此，即使用户通过公共 API 访问，聪网 Core Node 网络本身也形成了事实上的 L1 indexer 分布式验证结构。

长期看，比特币主网上的多协议资产越重要，越需要更多钱包、交易平台、浏览器、Core Node 和独立基础设施团队运行自己的 L1 indexer，并对同一套资产事实进行交叉验证。

分布式 indexer 的目标不是创造新的共识层，而是让更多节点能独立计算和校验同一套资产事实，降低单点错误、延迟、分叉和数据污染风险。对用户来说，这意味着钱包和 Agent 可以从多个来源交叉验证资产状态；对交易平台来说，这意味着充值、提现和风控可以建立在更稳健的数据基础上。

## 与 AI Agent 的关系

AI Agent 操作资产时，不能只相信钱包界面的余额变化。它需要读取 indexer 证据，并回答：

1. 这个资产来自哪个 L1 UTXO。
2. 这个 UTXO 是否确认，是否被花费。
3. 该资产协议事件是否有效。
4. 该资产是否已经 ascend 到聪网，还是仍在 BTC L1。
5. 通道承诺交易、L1/L2 indexer 和钱包本地状态是否一致。

这就是为什么 indexer 必须进入 SAT20 文档主线：它是 STP 安全操作、交易平台接入、浏览器展示和 AI Agent 验证的共同基础。


# STP 简介

STP 是 Satoshi Transcending Protocol，中文可称为聪穿越协议。它定义 BTC L1 资产如何进入聪网、在聪网中流动、再退出回 BTC L1。

STP 的核心不是“桥”，而是通道。

STP 必须和 indexer 一起理解。Indexer 说明 BTC L1 上的资产事实：哪个 UTXO 携带什么资产、是否确认、是否已花费、协议事件是否有效。STP 在这些资产事实之上建立通道控制权，让用户能进入聪网，也能在异常情况下退出。

## STP 做什么

| 动作               | 含义                  |
| ---------------- | ------------------- |
| open             | 打开用户与 Core Node 的通道 |
| splicing-in      | 把 BTC L1 资产加入已有通道   |
| unlock           | 把通道资产释放到聪网个人地址      |
| lock             | 把聪网个人资产重新纳入通道       |
| lock-with-expand | 容量不足时恢复用户资产的通道保护    |
| splicing-out     | 把通道资产退出到 BTC L1     |
| close            | 关闭通道                |
| punish           | 对旧承诺交易进行惩罚          |

这些动作不是孤立交易，而是协议状态机。它们可能涉及 BTC L1 交易、聪网交易、承诺状态更新、签名交换和链上确认。每一个跨层动作都需要 L1/L2 indexer 提供可复核证据，证明资产事实与通道状态一致。

## 普通用户不需要质押

普通用户连接 Core Node 打开私人通道时，不需要预先质押资产。质押只属于节点连接 bootstrap node，并准备升级为 Core Node 的路径。

普通用户通道与节点质押路径是两种不同场景。

## 对 Agent 的意义

STP 很适合被 AI Agent 操作，因为它有清晰的状态、交易、证据和恢复路径。Agent 可以把用户目标转换成可验证步骤：

1. 查询钱包和通道。
2. 检查安全快照。
3. 选择 open、splicing、unlock、lock 或 close。
4. 通过 indexer 轮询 L1/L2 交易和资产状态。
5. 遇到结果未知时进入恢复流程。

STP 的完整协议白皮书见 [STP 技术白皮书](/xie-yi-yu-an-quan/stp/stp)。


# 智能合约与 GAS

聪网的下一阶段重点是智能合约。STP + indexer 解决资产如何被识别、验证、安全进入和退出聪网；智能合约解决资产进入聪网后可以做什么。

有了智能合约，聪网才能从资产流通网络发展为应用网络。

## 为什么需要智能合约

比特币主网适合作为最终结算层，但不适合直接承载复杂应用。聪网智能合约在保持 BTC 原生资产事实、入口和退出能力的基础上，支持：

1. AMM 和资产交易。
2. 稳定币和支付。
3. 资产发行与组合。
4. 游戏、DePIN、RWA 等应用。
5. AI Agent 触发和管理的自动化合约。

## GAS 的作用

GAS 是合约网络的资源计量和费用入口。它不只是“一个资产”，还服务于三件事：

1. 防止无成本占用网络资源。
2. 为合约执行、验证、存储和交易处理定价。
3. 形成开发者、节点、应用和用户之间的经济连接。

围绕 GAS 的公开叙事聚焦用途、消耗路径、风险和限制。它可以成为生态关注点，但长期价值来自真实应用和资源消耗。

## 合约路线

聪网智能合约按多条路径推进：

| 阶段                    | 目标                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------ |
| 模板合约                  | 当前在 PWA `工具 -> 智能合约` 中测试 AMM 和限价单，用确定性模板支持常见交易场景                                           |
| EVM 兼容                | 当前在 PWA `工具 -> 智能合约` 中测试 `ConstantProductAMM` 和 `LimitOrderBook` 样本，复用 Solidity / EVM 开发生态 |
| Agent / Prediction 合约 | 当前公开测试网优先验证的 Agent 合约场景                                                                    |
| 自然语言合约                | 探索 AI Agent 与合约交互的新形态                                                                      |

当前普通用户可从 [Prediction 合约测试](/shi-yong-cong-wang/prediction-contract) 开始体验公开测试网；模板合约和 EVM 样本通过 PWA `工具 -> 智能合约` 交互。协议设计文档见 [智能合约协议](/xie-yi-yu-an-quan/smart-contracts/contracts)。


# AI Agent 与用户资产控制

AI Agent 不是 SAT20 的附属功能。它可能成为普通用户使用 STP、聪网和智能合约的重要入口。

STP、RSMC、承诺交易、惩罚交易、indexer 资产证据和跨层资产状态对多数用户都很复杂。Agent 的价值在于，它可以读懂这些证据，并把复杂协议转换成可执行、可解释、可验证的用户操作。

## Agent 的职责

Agent 负责：

1. 理解用户目标。
2. 查询钱包、通道、L1/L2 交易和 indexer。
3. 复核资产事实、确认数、花费状态和跨层证据。
4. 判断当前安全状态。
5. 调用钱包 adapter。
6. 解释每一步操作的作用。
7. 在不安全时停止。

Agent 的边界：

1. 不保存用户助记词。
2. 不绕过钱包授权。
3. 无法证明惩罚覆盖时停止移动资产。
4. 不把Core Node 口头状态当成安全证明。

## Skill 模型

SAT20 提供 SAT20 Agent Wallet skill，让 Agent 能通过统一 JSON adapter 操作钱包和 Core Node。

推荐顺序：

1. 用户先安装 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 用户在 PWA 内创建或导入钱包，完成备份、解锁和网络选择。
3. Agent 再安装 SAT20 Agent Wallet skill，并通过 PWA adapter 调用钱包。
4. Agent 先执行 `wallet.status`、`stp.status` 和 `stp.safety_snapshot`，验证安全状态后再移动资产。

安装 skill：

```bash
curl -fsSL https://raw.githubusercontent.com/sat20-labs/docs/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/install.sh | bash
```

更多说明见 [SAT20 Agent Wallet 安装与使用](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/sat20-agent-wallet)。


# 使用聪网


# 概述

Use 部分面向普通用户、资产玩家和社区成员。目标是让用户知道如何进入聪网、如何使用资产、如何退出，以及如何判断自己的资产仍在自己控制之下。

## 用户路径

| 目标                        | 指南                                                            |
| ------------------------- | ------------------------------------------------------------- |
| 安装钱包、连接聪网、理解资产位置          | [钱包与资产](/shi-yong-cong-wang/wallet-and-assets)                |
| 获取测试资产和测试 GAS             | [获取测试资产和测试 GAS](/shi-yong-cong-wang/test-assets-and-gas)      |
| 测试 Prediction / Agent 合约  | [Prediction 合约测试](/shi-yong-cong-wang/prediction-contract)    |
| 完成第一次 DEX Swap            | [完成第一次 Swap](/shi-yong-cong-wang/first-swap)                  |
| 提供 AMM 流动性                | [提供 AMM 流动性](/shi-yong-cong-wang/amm-liquidity)               |
| 使用限价单                     | [使用限价单](/shi-yong-cong-wang/limit-order)                      |
| 参与 Launchpad              | [参与 Launchpad](/shi-yong-cong-wang/launchpad)                 |
| 注册 DAO UID                | [注册 DAO UID](/shi-yong-cong-wang/dao-uid)                     |
| 向社区基金捐献                   | [向社区基金捐献](/shi-yong-cong-wang/community-fund-donation)        |
| 申请与审核空投                   | [申请与审核空投](/shi-yong-cong-wang/airdrop)                        |
| 加入社区 DEX                  | [加入社区 DEX](/shi-yong-cong-wang/community-dex)                 |
| 用 Explorer 和 Indexer 验证交易 | [使用 Explorer 验证交易](/shi-yong-cong-wang/explorer-verification) |
| 让 AI Agent 帮你查询和操作        | [使用 AI Agent 查询和操作](/shi-yong-cong-wang/ai-agent)             |
| 退出聪网和故障恢复                 | [退出聪网与故障恢复](/shi-yong-cong-wang/exit-and-recovery)            |
| 常见问题                      | [常见问题](/shi-yong-cong-wang/faq)                               |

带状态标签的页面表示内容仍在规划或对应系统仍在开发，保留入口便于后续逐步补齐。

## 基础资产路径

1. 安装 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)，创建或导入钱包并完成备份。
2. 连接默认 Core Node。
3. 打开 STP 通道。
4. 通过 Indexer 确认 BTC L1 资产 UTXO、确认数和协议状态。
5. 将 BTC L1 资产 splicing-in 到通道。
6. 使用 unlock 将资产释放到聪网个人地址。
7. 在聪网中转账、交易或使用合约。
8. 需要回到 BTC L1 时，使用 lock、splicing-out 或 close。

## 用户最需要理解的三件事

1. 聪网资产不是中心化桥托管资产。
2. Indexer 是资产事实层，帮助用户验证资产位于 BTC L1、通道还是聪网。
3. 用户需要能验证自己持有最新承诺交易和退出路径。
4. 任何主网价值移动都应通过钱包授权确认。

## 每篇指南的标准结构

每一篇用户指南都会尽量包含：

1. 操作前准备。
2. 具体步骤。
3. 成功结果。
4. 如何通过 Explorer / Indexer / 钱包验证。
5. 风险提醒。
6. 下一步。

## 常见场景

| 场景             | 应阅读                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| 我想把资产进入聪网      | [钱包与资产](/shi-yong-cong-wang/wallet-and-assets)                                                       |
| 我想测试智能合约投注     | [Prediction 合约测试](/shi-yong-cong-wang/prediction-contract)                                           |
| 我想第一次交易        | [完成第一次 Swap](/shi-yong-cong-wang/first-swap)                                                         |
| 我想提供流动性        | [提供 AMM 流动性](/shi-yong-cong-wang/amm-liquidity)                                                      |
| 我想用订单簿交易       | [使用限价单](/shi-yong-cong-wang/limit-order)                                                             |
| 我想参与社区活动       | [参与 Launchpad](/shi-yong-cong-wang/launchpad)                                                        |
| 我想理解资产如何被识别    | [Indexer：比特币资产事实层](/learn-li-jie-cong-wang/indexer)                                                  |
| 我想确认资产安全       | [资产安全模型](/learn-li-jie-cong-wang/security-model)                                                     |
| 我想让 Agent 帮我操作 | [AI Agent 与用户资产控制](/learn-li-jie-cong-wang/ai-agent)                                                 |
| 我想退出或恢复        | [退出聪网与故障恢复](/shi-yong-cong-wang/exit-and-recovery)                                                   |
| 我想了解测试网演练      | [SAT20 Agent Wallet 测试网验证记录](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/testnet-validation) |

## 风险边界

主网操作前，用户需要确认：

1. 网络是 mainnet 还是 testnet。
2. 资产名称和金额。
3. 目标地址。
4. 费用。
5. L1/L2 indexer 是否能查询到相关交易和资产状态。
6. 通道状态是否安全。
7. 钱包是否展示了授权弹窗。

如果钱包或 Agent 无法证明通道安全，就停止操作。

**页面状态：规划中（Planning）**


# 钱包与资产

本文面向普通用户，说明如何从钱包开始进入聪网。

后续页面会补充截图和更细步骤。当前先给出标准操作结构。

## 操作前准备

1. 安装 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 创建或导入钱包。
3. 完成助记词备份和解锁。
4. 确认当前网络是 mainnet 还是 testnet。
5. 准备需要使用的 BTC L1 资产或测试资产。

## 具体步骤

1. 打开钱包资产页。
2. 查询 BTC L1 资产和 UTXO。
3. 通过 Indexer 确认资产协议、数量、确认数和花费状态。
4. 如需进入聪网，按钱包提示打开或使用 STP 通道。
5. 等待相关交易确认。
6. 在钱包和 Explorer 中查看资产状态。

## 如何验证

1. 查看钱包显示的 txid。
2. 在 BTC L1 Explorer 中确认 L1 交易。
3. 在 SatoshiNet Explorer 中确认 L2 交易。
4. 用 Indexer 查询资产是否在正确地址、UTXO 或通道中。
5. 如果涉及 STP 通道，确认钱包能给出安全快照。

## 风险提醒

1. 不要把助记词发给 Agent 或任何网页表单。
2. 主网操作前确认资产、金额、地址和费用。
3. 如果钱包或 Agent 无法证明通道安全，停止操作。
4. 网络结果未知时，不要重复发起同一笔价值移动。

## 下一步

* [将资产进入聪网](/learn-li-jie-cong-wang/stp)
* [使用 Explorer 验证交易](/shi-yong-cong-wang/explorer-verification)
* [使用 AI Agent 查询和操作](/shi-yong-cong-wang/ai-agent)

**页面状态：规划中（Planning）**


# 获取测试资产和测试 GAS

测试网合约交互需要测试 GAS。当前 SAT20 PWA Wallet 已在工具首页提供测试网领水入口，用户可以先领取测试 GAS，再体验 Prediction 合约投注，以及 PWA `工具 -> 智能合约` 中的模板合约和 EVM 样本合约。

测试资产和测试 GAS 仅用于聪网测试网，没有主网价值。

## 领取测试 GAS

1. 打开 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 确认当前网络为聪网测试网。
3. 进入 `工具`。
4. 在工具首页找到测试网领水入口。
5. 点击领取测试 GAS。
6. 等待测试网交易确认或钱包余额刷新。

如果领取失败，可以稍后重试。测试网水龙头可能限制领取频率，或者因为测试网维护暂时不可用。

## 测试 GAS 用在哪里

测试 GAS 用于支付测试网资源消耗，包括：

1. 部署智能合约。
2. 调用智能合约。
3. 参与 Prediction 投注。
4. 触发合约结果确认和结算相关流程。
5. 测试钱包、工具页和 Explorer 的合约交互链路。

当钱包提示 GAS 不足时，先回到 `工具` 首页领取测试 GAS，或者等待已有领取交易确认。

## 测试资产

不同测试场景可能需要不同资产：

1. Prediction 合约可以使用测试网支持的投注资产。
2. AMM、限价单、Launchpad 和其他模板合约可能需要测试网资产、测试 GAS 和对应合约参数。
3. STP 跨层演练可能需要 BTC testnet4 资产和聪网测试网资产。

具体场景以对应用户指南为准。Prediction 合约测试见 [Prediction 合约测试](/shi-yong-cong-wang/prediction-contract)。

## 如何验证到账

1. 在 PWA Wallet 中查看测试 GAS 余额。
2. 打开测试网 Explorer 查询领取交易。
3. 检查交易确认状态。
4. 发起小额合约操作前，确认钱包显示可支付费用。

如果钱包余额和 Explorer 状态不一致，先等待索引器同步，不要连续重复提交相同操作。

## 风险边界

1. 测试资产只用于测试网。
2. 测试网可能重启、回滚或清理状态。
3. 测试网交易确认和索引可能延迟。
4. 任何真实资产操作都必须确认网络不是 testnet。

**页面状态：开发中（In Development）**


# Prediction 合约测试

Prediction 是当前聪网公开测试网优先开放的 Agent 合约场景。用户可以在 SAT20 PWA Wallet 中查看可投注比赛、参与投注，也可以在工具页部署新的 Prediction 合约。

本文面向测试网用户。Prediction 合约当前仅用于测试网演示和验证，不代表主网可用能力。

## 测试前准备

1. 安装或打开 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 确认钱包连接的是聪网测试网。
3. 在 PWA 的 `工具` 首页领取测试 GAS。
4. 等待钱包显示测试 GAS 到账。

合约部署、投注、结果确认和其他合约交互都需要测试 GAS。如果交易失败，先检查测试 GAS 是否足够。

## 参与投注

1. 打开 SAT20 PWA Wallet。
2. 进入 `市场`。
3. 打开 `Prediction`。
4. 查看当前可投注的比赛或事件。
5. 选择一个比赛，阅读标题、候选结果、投注截止时间、结果确认来源和最小投注单位。
6. 选择要投注的候选结果。
7. 输入投注金额。
8. 在钱包中确认交易和费用。
9. 等待测试网确认。
10. 回到 `市场 -> Prediction` 查看投注状态。

投注金额以交易转入合约地址的资产为准。页面上选择的候选结果只表达投注方向，资产数量由钱包构造并签名的交易决定。

## 部署 Prediction 合约

1. 打开 SAT20 PWA Wallet。
2. 进入 `工具`。
3. 确认已经领取测试 GAS。
4. 打开 Prediction 合约部署工具。
5. 填写比赛或事件标题。
6. 填写比赛说明。
7. 设置候选结果，例如主队胜、客队胜、平局，或其他明确可验证结果。
8. 设置比赛开始时间、投注截止时间和结果可确认时间。
9. 填写结果来源 URL。该 URL 应指向可公开验证比赛结果的网站或页面。
10. 设置投注资产和最小投注单位。
11. 检查参数后提交部署。
12. 在钱包中确认部署交易。
13. 等待测试网确认。
14. 部署成功后，在 `市场 -> Prediction` 查看新比赛。

部署者需要确保预测事件可以被验证。结果来源不清晰、候选结果不完整、时间设置不合理或最小投注单位不合理，都可能导致合约无法进入可投注状态或后续无法确认结果。

## 结果确认和结算

Prediction 合约的结果确认由测试网 Core Node Agent 执行。Agent 会在达到结果确认时间后，根据部署时指定的数据来源检查比赛结果，并提交结构化确认结果。

确认结果可能包括：

1. 某个候选结果胜出。
2. 比赛取消。
3. 结果无效。
4. 结果不可验证。

有明确赢家时，合约按规则分配奖池。没有可确认赢家、比赛取消或结果不可验证时，合约进入退款流程。具体协议规则见 [自然语言合约](/xie-yi-yu-an-quan/smart-contracts/agent)。

## 如何验证

用户不应只看页面余额，还应尽量检查证据：

1. 钱包中是否有投注交易 txid。
2. 合约地址是否收到对应投注资产。
3. 测试网 Explorer 是否能查到部署、投注和结果交易。
4. Prediction 页面是否展示相同的比赛状态和投注状态。
5. 结果确认后，是否存在对应的 Result TX。
6. 中奖或退款资产是否回到用户地址。

如果页面状态、钱包记录和 Explorer 证据不一致，应暂停继续投注，保留 txid 和截图，并反馈给 SAT20 Labs。

## 风险边界

1. 当前 Prediction 合约仅用于测试网。
2. 测试资产和测试 GAS 没有主网价值。
3. 测试网可能重启、回滚或调整规则。
4. 用户不应输入真实私钥、助记词或交易所账户信息。
5. 结果来源 URL 应使用公开可访问页面，不应依赖私人聊天、人工口头承诺或不可复核数据。

**页面状态：开发中（In Development）**


# 完成第一次 Swap

本文用于后续补充用户在聪网 DEX 中完成第一次 Swap 的完整手册。

当前先定义页面结构，待 DEX 测试网入口、截图和合约地址确认后补齐。

## 操作前准备

1. 已安装并解锁 SAT20 PWA Wallet。
2. 钱包连接到正确网络。
3. 钱包中有可用于测试的资产和测试 GAS。
4. 已确认目标 DEX 或社区 DEX 的域名和合约信息。

## 具体步骤

1. 打开 DEX 页面。
2. 连接 SAT20 PWA Wallet。
3. 选择输入资产和输出资产。
4. 查看价格、滑点、费用和预估结果。
5. 在钱包中确认交易。
6. 等待交易确认。
7. 在资产页查看结果。

## 如何验证

1. 记录交易 txid。
2. 在 SatoshiNet Explorer 查询交易状态。
3. 在 Indexer 查询输入和输出资产变化。
4. 如果交易涉及合约，查看合约 Result TX 或合约状态。

## 风险提醒

1. Swap 存在价格波动和滑点。
2. 测试网结果不代表主网流动性。
3. 主网交易前确认目标合约和域名来源。

**页面状态：规划中（Planning）**


# 提供 AMM 流动性

当前 PWA 钱包市场中的 AMM 属于 L2 市场通道合约能力，不是聪网智能合约。它运行在现有 L2 市场体系中，用于测试 AMM 池、swap 和流动性操作。

智能合约模板 AMM 是另一条测试路径，只能从 PWA `工具 -> 智能合约` 入口交互，不应和市场中的 AMM 混淆。

## 准备

1. 打开 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 确认连接聪网测试网。
3. 在 `工具` 首页领取测试 GAS。
4. 确认钱包中有 AMM 池所需的测试资产和测试聪。

## 添加流动性

1. 进入 PWA `市场` 或 DEX 中的 AMM 页面。
2. 选择测试网 AMM 池。
3. 查看池子资产、当前储备、价格和风险提示。
4. 输入要提供的资产数量和聪数量。
5. 设置最小可接受 LP 份额或滑点参数。
6. 在钱包中确认交易和测试 GAS。
7. 等待测试网确认。
8. 查看 LP 份额和池子余额变化。

添加流动性时，实际入池资产以钱包构造并签名的交易为准。页面参数用于表达滑点和最小输出保护。

## Swap

1. 选择买入或卖出方向。
2. 输入要交换的测试资产或测试聪。
3. 查看预估输出和最小可接受输出。
4. 钱包确认交易。
5. 等待市场交易状态更新。
6. 查看钱包余额变化。

如果滑点保护失败，市场合约会按通道合约规则退款或保持资产安全返回路径。

## 移除流动性

1. 打开自己的 LP 份额。
2. 输入要移除的 LP 数量。
3. 设置最小可接受资产和聪输出。
4. 钱包确认交易。
5. 等待市场交易状态更新。
6. 检查资产是否返回用户地址。

## 如何验证

1. 查看调用 txid。
2. 查看合约地址的资产变化。
3. 查看市场合约结果和相关交易输出。
4. 对比钱包余额、LP 份额和 Explorer 状态。
5. 确认 L2 市场状态和钱包资产状态一致。

## 风险边界

1. 当前市场 AMM 流动性测试仅用于测试网。
2. 测试资产没有主网价值。
3. 测试网池子价格可能很薄，不能代表真实价格。
4. 不要在状态不清楚时重复提交同一笔操作。

**页面状态：开发中（In Development）**


# 使用限价单

当前 PWA 钱包市场中的限价单属于 L2 市场通道合约能力，不是聪网智能合约。它用于测试市场中的订单创建、填单、取消和资产结算。

智能合约模板 LimitOrder 是另一条测试路径，只能从 PWA `工具 -> 智能合约` 入口交互，不应和市场中的限价单混淆。

## 准备

1. 打开 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 确认连接聪网测试网。
3. 在 `工具` 首页领取测试 GAS。
4. 确认钱包中有要挂单或填单的测试资产。

## 创建限价单

1. 进入 PWA `市场` 或 DEX 中的限价单页面。
2. 选择交易资产。
3. 选择买入或卖出方向。
4. 输入卖出资产数量和期望买入数量。
5. 检查价格、资产名称和测试 GAS。
6. 钱包确认交易。
7. 等待测试网确认。
8. 查看订单是否进入 open 状态。

创建订单时，卖出资产以 Call TX 转入合约地址的 funding output 为准。订单参数表达期望买入资产和数量。

## 填单

1. 在订单簿中选择一个可成交订单。
2. 查看对方卖出资产、自己需要支付的资产和数量。
3. 钱包确认填单交易。
4. 等待市场交易状态更新。
5. 检查买卖双方资产是否按成交结果转移。

## 取消订单

1. 打开自己的未完成订单。
2. 点击取消或 refund。
3. 钱包确认交易。
4. 等待市场交易状态更新。
5. 检查未成交资产是否返回用户地址。

## 如何验证

1. 创建订单交易是否转入合约地址。
2. 订单状态是否为 open、filled、partial 或 cancelled。
3. 填单交易是否转入正确支付资产。
4. 市场合约结果是否把成交资产转给双方。
5. 取消订单时，未成交资产是否按通道合约规则返回。
6. 钱包、市场页面和 Explorer 是否一致。

## 风险边界

1. 当前限价单测试仅用于测试网。
2. 测试网订单价格没有主网参考意义。
3. 网络错误或页面刷新失败时，先查询 txid 和订单状态。
4. 资产状态不清楚时，不要重复提交相同订单。

**页面状态：开发中（In Development）**


# 参与 Launchpad

本文用于后续补充 Launchpad 活动参与、资产领取、资格检查、交易验证和风险提示。

**页面状态：规划中（Planning）**


# 注册 DAO UID

本文用于后续补充 DAO UID 的用途、注册流程、钱包授权、状态验证和社区治理入口。

**页面状态：规划中（Planning）**


# 向社区基金捐献

本文用于后续补充向社区基金捐献资产、确认目标合约或地址、查看记录和验证资金状态的流程。

**页面状态：规划中（Planning）**


# 申请与审核空投

本文用于后续补充社区空投资格、申请流程、审核流程、领取流程和 Explorer / Indexer 验证方式。

**页面状态：规划中（Planning）**


# 加入社区 DEX

本文用于后续补充如何选择社区 DEX、确认域名和合约、连接钱包、查看资产、交易和验证结果。

**页面状态：规划中（Planning）**


# 使用 Explorer 验证交易

Explorer 是普通用户验证交易、资产和合约状态的入口。它不替代钱包授权，也不替代 Indexer 的底层 API，但它能把链上证据变成可读页面。

## 你可以验证什么

1. BTC L1 funding、splicing、close、punish 等交易。
2. SatoshiNet unlock、lock、anchor、deAnchor 等交易。
3. UTXO 是否存在、是否花费。
4. 资产数量和协议状态。
5. 合约部署、调用和 Result TX。
6. 通道地址、交易历史和跨层证据。

## 标准验证流程

1. 从钱包、DEX 或 Agent 复制 txid。
2. 判断它属于 BTC L1 还是 SatoshiNet L2。
3. 打开对应 Explorer。
4. 查询 txid、地址或 UTXO。
5. 确认高度、确认数、输入、输出和资产变化。
6. 如果状态和钱包不一致，等待 Indexer 收敛或停止继续操作。

## 对 STP 操作的验证

| 操作           | 需要验证                                   |
| ------------ | -------------------------------------- |
| open         | L1 funding、L2 anchor、channel ready     |
| splicing-in  | L1 资产进入通道地址、L2 anchor、commit height 前进 |
| unlock       | L2 个人地址获得可花费资产                         |
| lock         | L2 个人资产重新进入通道保护                        |
| splicing-out | L2 deAnchor、L1 输出到目标地址                 |
| punish       | 旧 commitment 上链、punish tx 上链、旧通道关闭     |

## 下一步

后续应为每类操作补充真实截图、Explorer URL 模板和 Indexer API 示例。

**页面状态：规划中（Planning）**


# 使用 AI Agent 查询和操作

AI Agent 可以帮助用户理解资产状态、检查 STP 通道安全、解释交易作用，并在用户授权后调用钱包 adapter。

Agent 不是钱包。Agent 不保存私钥、助记词或钱包密码。

## 推荐使用方式

1. 先安装并初始化 SAT20 PWA Wallet。
2. 在钱包内完成创建、导入、备份和解锁。
3. 安装 SAT20 Agent skill。
4. 让 Agent 通过 PWA adapter 调用 `wallet.status`。
5. 如果涉及 STP，调用 `stp.status` 和 `stp.safety_snapshot`。
6. Agent 给出安全判断和下一步建议。
7. 任何价值移动都在 PWA 钱包内确认。

## Agent 会告诉你什么

1. 资产现在在 BTC L1、STP 通道、聪网个人地址还是 pending 状态。
2. 当前通道是否 `READY_SAFE`。
3. 是否持有最新承诺交易。
4. 是否有 punish coverage。
5. 如果 Core Node 离线，你如何退出。
6. 如果发现旧 commitment，你是否能惩罚。
7. 本次操作有哪些 txid 和验证入口。

## 必须停止的情况

1. Agent 无法读取钱包状态。
2. 钱包没有展示授权弹窗。
3. 通道安全快照缺失。
4. 惩罚覆盖未知或缺失。
5. 网络结果未知但还没有完成 txid / reservation 检查。
6. 用户不理解主网操作的资产、金额、地址和费用。

**页面状态：开发中（In Development）**


# 退出聪网与故障恢复

本文用于后续补充用户从聪网回到 BTC L1、关闭通道、splicing-out、force close、punish、恢复钱包和处理未知网络结果的完整手册。

**页面状态：规划中（Planning）**


# 常见问题

本文用于后续整理用户在钱包、资产、STP 通道、DEX、Explorer、AI Agent、测试网和主网操作中的常见问题。

**页面状态：规划中（Planning）**


# 开发者中心


# 概述

Build 部分面向开发者、钱包、交易平台、Indexer、智能合约开发者和 AI Agent 构建者。

聪网生态需要的不只是一个协议，还需要完整的开发者系统：钱包、SDK、Indexer、合约模板、测试网、文档、示例和社区支持。STP 和 indexer 共同构成资产进入聪网的基础：前者保障控制权，后者提供资产事实。

## 快速开始

| 你要完成的第一件事                 | 入口                                                                        |
| ------------------------- | ------------------------------------------------------------------------- |
| 理解 EVM 开发者预览              | [EVM 开发者预览](/kai-fa-zhe-zhong-xin/evm-quickstart)                         |
| 查看 EVM 样本合约               | [EVM 样本合约](/kai-fa-zhe-zhong-xin/evm-sample-contracts)                    |
| 搭建社区 DEX / DAO            | [社区 DEX / DAO Quickstart](/kai-fa-zhe-zhong-xin/community-dex-quickstart) |
| 部署社区 DAO                  | [DAO Quickstart](/kai-fa-zhe-zhong-xin/dao-quickstart)                    |
| 部署智能合约模板 AMM 池            | [AMM Pool Quickstart](/kai-fa-zhe-zhong-xin/amm-pool-quickstart)          |
| 部署 Launchpad              | [Launchpad Quickstart](/kai-fa-zhe-zhong-xin/launchpad-quickstart)        |
| 部署智能合约模板限价单模块             | [Limit Order Quickstart](/kai-fa-zhe-zhong-xin/limit-order-quickstart)    |
| 运行核心节点、Indexer 或 Explorer | [基础设施 Quickstart](/kai-fa-zhe-zhong-xin/infrastructure-quickstart)        |
| 集成 Wallet SDK             | [Wallet SDK Quickstart](/kai-fa-zhe-zhong-xin/wallet-sdk-quickstart)      |
| 搭建白标 DEX                  | [White-label DEX](/kai-fa-zhe-zhong-xin/white-label-dex)                  |
| 构建 SatoshiNet AI Agent    | [AI Agent Quickstart](/kai-fa-zhe-zhong-xin/ai-agent-quickstart)          |
| 查看合约模板状态                  | [合约模板目录](/kai-fa-zhe-zhong-xin/contract-template-catalog)                 |
| 集成钱包或交易平台                 | [交易平台与钱包接入](/kai-fa-zhe-zhong-xin/exchange-and-wallet)                    |
| 查询当前权威 API 源码入口           | [API 源码地图](/kai-fa-zhe-zhong-xin/api-source-map)                          |

带状态标签的页面表示内容仍在规划或对应系统仍在开发，保留入口便于后续逐步补齐。独立 Quickstart 需要补齐环境要求、测试网地址、示例代码、预期输出、Explorer 验证和常见错误。

## 开发者路径

| 目标          | 路径                                                              |
| ----------- | --------------------------------------------------------------- |
| 构建 STP 客户端  | 阅读 STP 客户端接入指南，实现 JSON adapter，并用测试网验收清单验证                      |
| 接入钱包        | 使用 PWA Wallet adapter 或实现自己的安全钱包边界                              |
| 接入交易平台      | 关注充值提现、L1/L2 状态、通道状态和 indexer                                   |
| 查找 API 入口   | 使用 API 源码地图定位 L1 indexer、聪网 RPC、L2 indexer 和钱包 WASM/PWA adapter |
| 接入 Indexer  | 理解 BTC L1 与聪网 L2 的资产事实层，处理多协议资产、确认数、reorg 和跨层证据                 |
| 构建合约应用      | 从模板合约和 GAS 模型开始                                                 |
| 构建 AI Agent | 先接入 PWA 钱包安全边界，再安装 SAT20 Agent Wallet skill，实现安全验证和授权流程         |
| 运行基础设施      | 了解 Core Node、indexer、explorer 和测试网                              |

## 开始

1. 阅读 [开发者快速开始](/kai-fa-zhe-zhong-xin/quickstart)。
2. 选择一个可运行 quickstart，先在测试网完成一次真实操作。
3. 阅读 [API 源码地图](/kai-fa-zhe-zhong-xin/api-source-map)，确认当前权威源码入口。
4. 阅读 [Indexer 接入与资产事实层](/kai-fa-zhe-zhong-xin/indexer)。
5. 阅读 [STP 第三方客户端接入指南](/xie-yi-yu-an-quan/stp/client-integration)。
6. 阅读 [STP 第三方客户端实现验收清单](/xie-yi-yu-an-quan/stp/implementation-checklist)。
7. 如果你要做交易平台或钱包，阅读 [交易平台与钱包接入](/kai-fa-zhe-zhong-xin/exchange-and-wallet)。

## 原则

1. Core Node 状态不是最终事实。
2. 单个 indexer 响应不是不可质疑的最终事实；关键操作需要 txid、vout、height、confirmations 和跨源证据。
3. 余额显示不是资产安全证明。
4. 主网操作保留用户授权。
5. 缺少承诺交易或惩罚覆盖时停止价值移动。
6. 对结果未知的网络错误，按“可能已经成功”处理。


# 开发者快速开始

本文给出开发者进入 SAT20 / 聪网生态的最短路径。

## 先选择一个可运行目标

| 目标                      | 指南                                                                        |
| ----------------------- | ------------------------------------------------------------------------- |
| 理解 EVM 开发者预览            | [EVM 开发者预览](/kai-fa-zhe-zhong-xin/evm-quickstart)                         |
| 查看 EVM 样本合约             | [EVM 样本合约](/kai-fa-zhe-zhong-xin/evm-sample-contracts)                    |
| 搭建社区 DEX / DAO          | [社区 DEX / DAO Quickstart](/kai-fa-zhe-zhong-xin/community-dex-quickstart) |
| 部署社区 DAO                | [DAO Quickstart](/kai-fa-zhe-zhong-xin/dao-quickstart)                    |
| 部署 AMM 池                | [AMM Pool Quickstart](/kai-fa-zhe-zhong-xin/amm-pool-quickstart)          |
| 部署 Launchpad            | [Launchpad Quickstart](/kai-fa-zhe-zhong-xin/launchpad-quickstart)        |
| 部署限价单模块                 | [Limit Order Quickstart](/kai-fa-zhe-zhong-xin/limit-order-quickstart)    |
| 运行核心节点、Indexer、Explorer | [基础设施 Quickstart](/kai-fa-zhe-zhong-xin/infrastructure-quickstart)        |
| 集成 Wallet SDK           | [Wallet SDK Quickstart](/kai-fa-zhe-zhong-xin/wallet-sdk-quickstart)      |
| 搭建白标 DEX                | [White-label DEX](/kai-fa-zhe-zhong-xin/white-label-dex)                  |
| 构建 SatoshiNet AI Agent  | [AI Agent Quickstart](/kai-fa-zhe-zhong-xin/ai-agent-quickstart)          |
| 查看合约模板状态                | [合约模板目录](/kai-fa-zhe-zhong-xin/contract-template-catalog)                 |
| 集成钱包或交易平台               | [交易平台与钱包接入](/kai-fa-zhe-zhong-xin/exchange-and-wallet)                    |

带状态标签的页面表示内容仍在规划或对应系统仍在开发。未达到可运行标准前，页面会保留状态说明和待补清单。

## 选择你要构建什么

| 你要构建           | 起点                                            |
| -------------- | --------------------------------------------- |
| STP 钱包或客户端     | `sat20-agent-wallet` skill 与 adapter contract |
| Indexer / 数据服务 | L1/L2 indexer、资产事实层和多协议资产状态                   |
| 聪网应用           | 智能合约文档与测试网                                    |
| 交易平台接入         | Indexer、STP 状态和充值提现流程                         |
| AI Agent       | SAT20 Agent Wallet skill、PWA adapter、安全验证矩阵   |
| 区块浏览器或数据服务     | L1/L2 indexer 和交易状态模型                         |

## 安装钱包与 Agent Skill

面向普通用户和主网场景，先安装并初始化 SAT20 PWA Wallet，再安装 SAT20 Agent Wallet skill。PWA 钱包是私钥、助记词、签名、授权弹窗和通道数据库的安全边界；skill 是 Agent 的操作知识和工作流。

安装 SAT20 PWA Wallet：

```
https://sat20.org/pwa/?install=1
```

在 PWA 内创建或导入钱包、完成备份并解锁后，再安装 skill：

```bash
curl -fsSL https://raw.githubusercontent.com/sat20-labs/docs/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/install.sh | bash
```

安装后，Agent 应通过 `SAT20_ADAPTER_URL` 或 `SAT20_CLIENT_CMD` 调用钱包 adapter。

## 实现一个 Adapter

最小 adapter 应支持：

1. `wallet.status`
2. `stp.status`
3. `stp.safety_snapshot`
4. `stp.open`
5. `stp.splicing_in`
6. `stp.unlock`
7. `stp.lock`
8. `stp.splicing_out`
9. `stp.transaction`

完整契约见 [adapter contract](https://github.com/sat20-labs/docs/blob/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/references/adapter-contract.md)。

## 接入 Indexer

如果你构建钱包、交易平台、浏览器或 Agent，先阅读 [Indexer 接入与资产事实层](/kai-fa-zhe-zhong-xin/indexer)。最小实现应能查询 L1 UTXO 资产、交易确认、花费状态、L2 UTXO、ascend / descend 事件和通道相关状态。

当前接口仍在快速迭代，先使用 [API 源码地图](/kai-fa-zhe-zhong-xin/api-source-map) 定位权威源码入口。旧 Swagger 只覆盖早期 ORDX indexer 的一部分接口，不作为当前 SAT20 / 聪网完整 API 文档。

## 测试网验收

开发者至少应在测试网上验证：

1. 打开普通 client-core 通道。
2. splicing-in 一种协议资产。
3. unlock / lock 往返。
4. splicing-out 回 BTC L1。
5. 导出承诺交易。
6. 验证 punish coverage。
7. 处理未知网络结果。
8. 通过 indexer 复核 L1/L2 资产证据链。
9. 部署或调用至少一个测试网智能合约，例如 Prediction，或在 PWA `工具 -> 智能合约` 中测试模板 AMM、模板限价单、EVM `ConstantProductAMM`、EVM `LimitOrderBook`。

验收清单见 [STP 第三方客户端实现验收清单](/xie-yi-yu-an-quan/stp/implementation-checklist)。

**页面状态：规划中（Planning）**


# EVM 开发者预览

本文是面向 Solidity / EVM 开发者的测试网预览入口。聪网智能合约框架已经完成开发并进入公开测试网，EVM Runtime、模板合约和 Agent 合约正在围绕钱包、Explorer、Indexer、RPC 和开发者工具持续迭代。

当前测试网已经开放 Agent / Prediction 合约体验，并上线了两个 EVM 标准样本合约：`ConstantProductAMM` 和 `LimitOrderBook`。EVM 开发者可以先通过样本合约理解 Solidity 合约如何与聪网 UTXO 资产模型、ABI calldata、Result TX 和 contract state root 组合。

## 当前可做

1. 通过 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1) 进入测试网。
2. 在 PWA `工具` 首页领取测试 GAS。
3. 在 `市场 -> Prediction` 体验 Agent 合约调用。
4. 在 PWA `工具 -> 智能合约` 体验或部署 `ConstantProductAMM`、`LimitOrderBook` EVM 样本合约。
5. 阅读智能合约协议、EVM 合约规则和资产预编译接口。
6. 准备 Solidity 合约迁移时需要处理的 UTXO 资产模型差异。

## EVM 开发者需要理解

1. EVM 执行 Solidity / EVM 状态机，但聪网真实资产来源和结算由 UTXO 模型表达。
2. 合约内部 ERC20 或应用账本不等于聪网原生资产余额。
3. EVM invoke 的 payload 是 Solidity ABI calldata；PWA 可以根据函数签名和参数生成 calldata，也可以接受原始 calldata。
4. 资产和聪的业务输入来自转入合约地址的 funding output，不应在 Solidity 参数中重复填写同一经济数量；测试 GAS / Result fee 用于支付执行和结果交易费用。
5. 合约要转移聪网原生资产，需要通过资产预编译接口生成 Asset Intent，再由 canonical Result TX 结算。
6. EVM gas unit 和测试 GAS 资产不是同一个单位，当前由协议参数换算。
7. 合约状态参与 contract state root。
8. 部署和调用都需要测试 GAS。
9. 测试网期间，工具链和 RPC 可能调整。

## PWA 交互模型

部署 EVM 合约时，PWA 从节点读取当前 compiler config，使用固定编译配置生成 init code。当前测试阶段默认配置为 `solc 0.8.30`、`evmVersion=paris`、optimizer `runs=200`、metadata `bytecodeHash=none`，并以单文件 Solidity 源码为主。有效 Deploy TX 必须在同一区块内生成 canonical Result TX，源码、ABI、compiler config 和 code hash 可以作为 metadata 提交给 L2 indexer，用于钱包、Explorer 和工具展示。

调用 EVM 合约时，PWA 的基本流程是：

1. 选择合约地址。
2. 填写函数签名、参数、sats、funding assets 和 gas limit，或直接填写 `calldataHex`。
3. 点击生成 calldata，并用节点的 estimate 接口检查 calldata、funding 和 gas limit 是否可接受。
4. 在签名前确认 calldata 与当前 JSON 参数一致。
5. 签名并广播 Invoke TX。
6. 如果本次执行产生资产转移、退款、revert 或 out of gas，检查同区块 canonical Result TX。

示例调用 JSON：

```json
{
  "function": "swapAssetForSat(uint256)",
  "args": ["1000"],
  "sats": "0",
  "funding": [
    {
      "assetName": "brc20:f:ooxx",
      "amount": "100000"
    }
  ],
  "gasLimit": 5000000
}
```

这里的 `args` 只用于 ABI 编码，`funding` 才是本次调用真正转入合约地址的资产输入。合约应通过 `fundingAssetAmount`、`fundingSats` 和 `claimFundingAsset` 读取并认领这些输入。

## 待公开参数

| 项目          | 内容                                                       |
| ----------- | -------------------------------------------------------- |
| RPC         | 测试网 EVM RPC / 合约 RPC 入口                                  |
| Chain ID    | 测试网 Chain ID                                             |
| 示例仓库        | 最小 Solidity 合约、部署脚本和调用脚本                                 |
| CLI 流程      | install、compile、deploy、generate calldata、estimate、invoke |
| Explorer 验证 | Deploy TX、Invoke TX、Result TX、event、state root           |
| 钱包接口        | PWA / Wallet SDK 合约部署、调用、calldata 生成和 estimate 接口        |
| 常见错误        | GAS 不足、RPC 不匹配、合约地址错误、Result TX 未生成                      |

## 当前参考

* [智能合约协议](/xie-yi-yu-an-quan/smart-contracts/contracts)
* [EVM 合约](/xie-yi-yu-an-quan/smart-contracts/evm)
* [EVM 样本合约](/kai-fa-zhe-zhong-xin/evm-sample-contracts)
* [智能合约与 GAS](/learn-li-jie-cong-wang/smart-contracts-and-gas)
* [Prediction 合约 Quickstart](/kai-fa-zhe-zhong-xin/prediction-contract-quickstart)

**页面状态：开发中（In Development）**


# EVM 样本合约

聪网 EVM Runtime 已进入公开测试网测试阶段。当前测试网已经部署并验证 EVM 标准样本合约，用于展示 Solidity 应用如何在聪网 EVM Runtime 上运行，并通过聪网原生资产接口完成资产读取、认领和 Result TX 结算。

当前测试网上线的两个 EVM 标准样本合约是：

1. `ConstantProductAMM`
2. `LimitOrderBook`

本文先记录当前样本合约的开发者视角。测试网合约地址、txid、Explorer 链接和 PWA 操作截图需要在后续测试记录中补齐。

样本源码当前位于 [`sat20wallet/sdk/e2e/testdata/contracts/StandardApps.sol`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/e2e/testdata/contracts/StandardApps.sol)。该源码是测试网标准样本的参考实现，不代表未来主网合约模板只能采用这两个业务形态。

## 当前样本

| 样本                   | 类型              | 验证重点                                               |
| -------------------- | --------------- | -------------------------------------------------- |
| `ConstantProductAMM` | Solidity AMM 样本 | 添加流动性、swap、移除流动性、资产预编译接口、ABI calldata、Result TX    |
| `LimitOrderBook`     | Solidity 限价单样本  | 创建订单、填单、取消订单、订单状态视图、资产预编译接口、ABI calldata、Result TX |

如果测试网后续切换样本合约，应同步更新本页和 [EVM 开发者预览](/kai-fa-zhe-zhong-xin/evm-quickstart)。

## ConstantProductAMM

`ConstantProductAMM` 是 EVM Runtime 上的常数乘积 AMM 样本合约。它用 Solidity 实现 AMM 状态机，同时通过聪网资产预编译接口处理真实资产输入和输出。

核心接口包括：

| 接口                                                                          | 用途                   |
| --------------------------------------------------------------------------- | -------------------- |
| `addLiquidity(uint256 minLiquidity)`                                        | 添加资产和聪流动性，铸造内部 LP 份额 |
| `swapSatForAsset(string minAssetOut)`                                       | 输入聪，输出目标资产           |
| `swapAssetForSat(uint256 minSatOut)`                                        | 输入目标资产，输出聪           |
| `removeLiquidity(uint256 liquidity, string minAssetOut, uint256 minSatOut)` | 移除 LP 份额，取回资产和聪      |
| `liquidityOfCaller()`                                                       | 查询当前调用者 LP 份额        |
| `reserves()`                                                                | 查询池子资产、资产储备、聪储备和总 LP |
| `quoteSatForAsset(uint256 satIn)`                                           | 估算输入聪可获得的资产          |
| `quoteAssetForSat(string assetIn)`                                          | 估算输入资产可获得的聪          |
| `quoteAddLiquidity(string assetIn, uint256 satIn)`                          | 估算添加流动性可获得的 LP 份额    |
| `quoteRemoveLiquidity(uint256 liquidity)`                                   | 估算移除流动性可获得的资产和聪      |

测试目标：

1. 部署 Solidity AMM 合约，构造参数指定池子管理的资产名称。
2. 调用时由 PWA 根据函数签名和参数生成 ABI calldata。
3. 通过 funding output 向合约输入资产和聪；这些经济输入不由 Solidity 参数重复决定。
4. 合约调用 `fundingAssetAmount`、`fundingSats` 和 `claimFundingAsset` 识别并认领输入资产。
5. 合约更新储备和 LP 状态。
6. Swap 时合约通过 `transferAsset` 生成资产转移 intent。
7. 聪网通过 canonical Result TX 完成输出资产结算。
8. `reserves()` 和 Explorer / Indexer 展示的合约资产状态保持可解释一致。

`ConstantProductAMM` 与模板 AMM 合约用途相似，但它验证的是 Solidity / EVM 路径：开发者可以用 EVM 合约表达 AMM 逻辑，资产结算仍由聪网 UTXO 资产层和 Result TX 负责。

## LimitOrderBook

`LimitOrderBook` 是 EVM Runtime 上的限价单样本合约。它用 Solidity 维护订单状态，并通过聪网资产预编译接口处理挂单、填单、取消和资产结算。

核心接口包括：

| 接口                                                                 | 用途                           |
| ------------------------------------------------------------------ | ---------------------------- |
| `createOrder(string sellAsset, string buyAsset, string buyAmount)` | 创建订单，卖出资产来自本次 funding output |
| `fillOrder(uint256 orderId)`                                       | 填充订单，支付资产来自本次 funding output |
| `cancelOrder(uint256 orderId)`                                     | Maker 取消未完成订单并取回剩余卖出资产       |
| `activeOrderCount()`                                               | 查询活跃订单数量                     |
| `activeOrderId(uint256 activeIndex)`                               | 按活跃索引查询订单 ID                 |
| `orderInfo(uint256 orderId)`                                       | 查询订单状态                       |
| `stateView()`                                                      | 返回订单簿 JSON 视图                |
| `quoteFillOrder(uint256 orderId, string paidIn)`                   | 估算填单可获得的卖出资产数量               |

核心流程：

1. Maker 创建订单，把卖出资产转入合约地址。
2. 调用时由 PWA 根据 `createOrder(string,string,string)` 生成 ABI calldata；calldata 中的 `buyAmount` 是订单期望收到的买入资产数量，卖出资产数量来自 funding output。
3. 合约读取 funding output，确认卖出资产数量。
4. 合约记录订单状态，包括 maker、接收地址、卖出资产、买入资产、剩余卖出数量和剩余买入数量。
5. Taker 调用 `fillOrder(uint256)` 并通过 funding output 转入订单要求的买入资产。
6. 合约计算成交比例，更新剩余订单状态。
7. 合约通过 `transferAsset` 把支付资产转给 maker，把卖出资产转给 taker。
8. Maker 可以取消未完成订单，合约通过 Result TX 退回剩余卖出资产。

测试目标：

1. 验证 EVM 合约可以维护订单簿状态。
2. 验证挂单资产由 funding output 提供，而不是由 calldata 中的金额决定。
3. 验证填单资产由 funding output 提供。
4. 验证部分成交、完全成交和取消订单都能通过 Result TX 结算。
5. 验证订单状态视图、钱包余额和 Explorer / Indexer 证据一致。

`LimitOrderBook` 与模板限价单合约用途相似，但它验证的是 Solidity / EVM 路径：订单簿状态由 EVM storage 表达，资产转移仍由聪网原生资产接口和 canonical Result TX 结算。

## 预编译资产接口

EVM 合约不能直接花费 UTXO。它通过聪网资产预编译接口表达资产读取和转移意图。

常用接口包括：

| 接口                                                   | 用途                                   |
| ---------------------------------------------------- | ------------------------------------ |
| `balanceOf(address,string)`                          | 查询 EVM 地址对应合约地址的指定资产余额               |
| `fundingAssetAmount(string)`                         | 查询本次 Call TX funding output 中的指定资产数量 |
| `claimFundingAsset(string,string)`                   | 认领本次 funding 中的指定资产，使其进入合约业务处理       |
| `fundingSats()`                                      | 查询本次 Call TX 转入合约地址的聪数量              |
| `callerAddress()`                                    | 查询调用者在聪网中的接收地址，用于退款和资产归属             |
| `transferAsset(string,string,string,bytes)`          | 声明一笔资产转移 intent                      |
| `transferAssets(string[],string[],string[],bytes[])` | 一次声明多笔资产转移 intent                    |
| `compareAmount(string,string)`                       | 按资产 Decimal 语义比较数量                   |

完整规则见 [EVM 合约](/xie-yi-yu-an-quan/smart-contracts/evm)。

## 测试网操作路径

当前推荐路径：

1. 打开 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 确认连接聪网测试网。
3. 在 `工具` 首页领取测试 GAS。
4. 进入 PWA `工具 -> 智能合约` 中的 EVM 合约测试或部署工具。
5. 使用 Solidity 源码编译入口，或使用 PWA 提供的标准样本入口，准备 `ConstantProductAMM` 或 `LimitOrderBook` 的 init code。
6. 部署合约，并等待 Deploy TX 和同区块 Result TX。
7. 调用样本接口前，先填写函数签名、参数、sats、funding assets 和 gas limit，点击生成 calldata 并完成 estimate。
8. 确认 calldata 与当前参数一致后签名广播。
9. 在钱包、工具页或 Explorer 中查看 Invoke TX、Result TX、状态视图和资产变化。

如果 PWA 暂未对普通用户开放完整源码部署体验，可以先使用 PWA 提供的标准样本入口。CLI、RPC、示例仓库和更完整的 Solidity 开发者流程仍处于公开测试网迭代阶段。

## 验证清单

每个 EVM 样本都应能给出：

1. Deploy TX。
2. 合约地址。
3. Invoke TX。
4. Result TX，如果该调用产生资产转移、退款、revert 或 out of gas。
5. 合约状态变化。
6. contract state root 所在区块。
7. 合约 metadata，包括源码、ABI、compiler config 和 code hash。
8. calldata 生成记录，以及本次调用的 sats、funding assets 和 gas limit。

## 限制

1. 当前为测试网样本，不代表主网开放。
2. 测试网参数、工具入口和样本合约可能调整。
3. EVM 内部余额不等同于聪网原生资产余额。
4. 函数参数不应重复表达已经由 funding output 表达的经济输入。
5. 真正的资产转移必须通过 Result TX 验证。
6. Solidity 合约必须遵守聪网 UTXO 资产模型和预编译资产接口规则。

**页面状态：开发中（In Development）**


# Prediction 合约 Quickstart

Prediction 是当前聪网公开测试网优先开放的 Agent 合约场景。它用于验证自然语言 / Agent 合约在聪网智能合约框架中的基本闭环：部署、ready、投注、结果确认、Result TX、派奖或退款。

本文面向测试网部署者和开发者。普通用户操作步骤见 [Prediction 合约测试](/shi-yong-cong-wang/prediction-contract)。

## 当前状态

| 项目   | 状态                                         |
| ---- | ------------------------------------------ |
| 合约类型 | Agent 合约 / Natural Language Contract       |
| 子类型  | `prediction`                               |
| 可用环境 | 聪网公开测试网                                    |
| 主网状态 | 暂未开放                                       |
| 推荐入口 | SAT20 PWA Wallet `工具` 和 `市场 -> Prediction` |
| 费用资产 | 测试 GAS                                     |

## 基本流程

1. 部署者在 PWA `工具` 中创建 Prediction 合约。
2. 合约部署交易进入聪网测试网。
3. Core Node Agent 审核合约内容，调用 `ready`。
4. 合约进入可投注状态。
5. 用户在 `市场 -> Prediction` 选择候选结果并投注。
6. 投注截止后，Core Node Agent 根据指定数据来源确认结果。
7. 合约生成 canonical Result TX。
8. 用户获得派奖或退款。

## 部署参数

Prediction 合约部署参数应包含：

| 字段              | 含义                            |
| --------------- | ----------------------------- |
| `title`         | 比赛或事件标题                       |
| `description`   | 事件说明，帮助用户理解预测对象               |
| `time_base`     | 时间基准，通常为 unix 时间，也可以按协议支持使用高度 |
| `event_time`    | 比赛或事件发生时间                     |
| `bet_deadline`  | 停止投注时间                        |
| `confirm_after` | Agent 开始确认结果的时间               |
| `source_url`    | 结果来源 URL                      |
| `bet_asset`     | 投注资产名称                        |
| `min_bet_unit`  | 最小投注单位                        |
| `outcomes`      | 候选结果列表                        |

候选结果应明确、互斥，并能被结果来源验证。不要使用“可能”“大概”“看情况”这类无法形成清晰结算结果的描述。

## 示例 payload

```json
{
  "subtype": "prediction",
  "title": "Team A vs Team B",
  "description": "Predict the final match winner.",
  "time_base": "unix",
  "event_time": 1780310400,
  "bet_deadline": 1780306800,
  "confirm_after": 1780396800,
  "source_url": "https://example.com/match/team-a-vs-team-b",
  "bet_asset": "::",
  "min_bet_unit": "10000",
  "outcomes": [
    { "id": "a", "text": "Team A wins" },
    { "id": "b", "text": "Team B wins" },
    { "id": "c", "text": "Draw" }
  ]
}
```

字段细节以 [自然语言合约](/xie-yi-yu-an-quan/smart-contracts/agent) 中的 Prediction 协议定义为准。

## 部署检查

部署前应检查：

1. 钱包在测试网。
2. 钱包有足够测试 GAS。
3. `bet_deadline` 早于 `event_time`。
4. `confirm_after` 不早于事件结果可公开查询的时间。
5. `source_url` 是公开可访问页面。
6. 候选结果至少两个，并且不会互相重叠。
7. `min_bet_unit` 与目标测试资产的精度和用户体验匹配。

## 投注调用

用户投注时，调用参数只表达候选结果：

```json
{
  "outcome_id": "a"
}
```

投注金额以 Call TX 转入合约地址的 funding output 为准，不应在调用参数中重复表达金额。这样可以避免 UI 参数和链上资产输入不一致。

## 结果确认

结果确认由 Core Node Agent 发起。确认参数包括：

```json
{
  "result_type": "outcome",
  "outcome_id": "a",
  "result_url": "https://example.com/match/team-a-vs-team-b/result",
  "result": "Team A 2-1 Team B",
  "observed_at": 1780314000,
  "agent_version": 1,
  "model_version": "model-v1"
}
```

`result_url` 应属于部署时 `source_url` 指定的网站范围。合约 runtime 处理结构化确认结果，索引器、浏览器和审计工具可以根据 `result_url`、`result`、`observed_at` 和 Agent 日志复核确认过程。

## 验证 Result TX

开发者和测试者应关注：

1. Deploy TX 是否成功。
2. Ready Result TX 是否出现。
3. Bet TX 是否被合约接受。
4. Confirm 调用是否由 Core Node Agent 发起。
5. 结算 Result TX 是否按协议分配奖池或退款。
6. contract state root 是否随区块更新。
7. 钱包、市场和 Explorer 展示是否一致。

如果合约状态和资产分配不一致，应优先保留合约地址、txid、区块高度、页面截图和钱包日志。

## 与其他合约类型的关系

Prediction 不是 EVM 合约，不需要 Solidity、ABI 或 bytecode。它也不是通道合约，不依赖通道两端共同验证。Prediction 属于聪网智能合约体系，由全网验证合约调用、Result TX 和 state root。

EVM 合约适合复用 Solidity 生态；模板合约适合高频、规则固定、需要节点内置确定性 runtime 的场景；Prediction 适合测试 Agent 如何把外部可验证事件转化为结构化合约结果。

**页面状态：开发中（In Development）**


# 搭建社区 DEX / DAO

本文用于指导社区从零开始搭建测试网 DEX / DAO 原型。当前先定义标准流程，后续补充具体部署脚本、配置文件和截图。

## 目标

一个 BTC 社区应能在测试网上完成：

1. 选择社区资产。
2. 部署或配置 DEX 前端。
3. 配置 AMM 或限价单模块。
4. 配置 DAO 或社区基金最小治理流程。
5. 接入钱包、Indexer 和 Explorer。
6. 完成一次测试交易。
7. 生成用户教程和风险提示。

## 操作前准备

1. 社区名称、域名和品牌素材。
2. 资产协议、ticker、数量和当前流动性。
3. 钱包和签名人安排。
4. 测试网资产和测试 GAS。
5. 所需模块：DEX、AMM、限价单、Launchpad、DAO、Explorer。

## 推荐步骤

1. 阅读 [Community Stack](/sheng-tai-luo-di-lu-jing-she-qu-zi-you-ji-chu-she-shi/community-stack)。
2. 选择最小模块组合。
3. 生成部署配置。
4. 在测试网部署合约或启用模板。
5. 配置 DEX 前端和后台。
6. 使用 SAT20 PWA Wallet 完成连接和授权。
7. 完成一次 Swap 或限价单测试。
8. 在 Explorer 和 Indexer 中验证结果。
9. 提交到 [Built on SatoshiNet](/sheng-tai-jian-she/built-on-satoshinet)。

## 验收标准

1. 用户能打开社区 DEX。
2. 用户能连接钱包。
3. 用户能看到资产和交易对。
4. 用户能完成一次测试网交易。
5. Explorer 能展示交易。
6. 社区能说明如何退出、如何验证资产、如何获得支持。

**页面状态：规划中（Planning）**


# 部署社区 DAO

本文用于后续补充社区 DAO 的模板选择、参数配置、签名人设置、测试网部署、治理操作和 Explorer 验证。

**页面状态：规划中（Planning）**


# 部署智能合约模板 AMM 池

AMM 模板是当前聪网公开测试网上线的智能合约模板之一。它用于验证 AMM 逻辑在聪网智能合约框架中的全网共识执行、canonical Result TX 和 contract state root。

注意：PWA `市场` 或 DEX 中的 AMM 是 L2 市场通道合约能力，不是本文讨论的智能合约模板 AMM。本文讨论的模板 AMM 只能从 PWA `工具 -> 智能合约` 入口交互。

## 当前状态

| 项目   | 状态                |
| ---- | ----------------- |
| 合约类型 | Template Contract |
| 模板   | AMM               |
| 可用环境 | 聪网公开测试网           |
| 主网状态 | 暂未开放              |
| 费用资产 | 测试 GAS            |
| 交互入口 | PWA `工具 -> 智能合约`  |

## 基本流程

1. 部署者选择交易资产。
2. 在 PWA `工具 -> 智能合约` 中选择 AMM 模板。
3. 设置初始资产数量、初始聪数量和常数 K。
4. 部署 AMM 模板合约。
5. 向合约添加初始流动性，使资产池、聪池和 `asset * sats >= K` 满足 ready 条件。
6. 调用 `swap` 买入或卖出。
7. 调用 `addliq` 或 `removeliq` 调整流动性。
8. 出块节点生成 canonical Result TX。
9. 钱包、Explorer 和 indexer 展示池子状态、交易结果和 LP 份额。

## 部署参数

AMM 模板部署内容至少包括：

| 参数     | 含义                 |
| ------ | ------------------ |
| 资产名称   | 池子交易资产，使用聪网资产名称格式  |
| 初始资产数量 | 进入池子的初始资产数量        |
| 初始聪数量  | 进入池子的初始 satoshi 数量 |
| K      | 初始常数乘积约束           |

测试网部署前应确认：

1. 钱包有测试 GAS。
2. 目标资产已经在聪网上可用。
3. 初始资产和初始聪能够进入合约地址。
4. 初始 K 与流动性规模匹配。
5. 部署者理解测试网可能重启或回滚。

## 调用接口

AMM 模板当前核心动作：

| 动作          | 说明     |
| ----------- | ------ |
| `swap`      | 买入或卖出  |
| `refund`    | 取回可退资产 |
| `addliq`    | 添加流动性  |
| `removeliq` | 移除流动性  |

输入金额以 Call TX 转入合约地址的 funding output 为准。调用参数只应表达方向、最小可接受输出、滑点约束、deadline 等不能从 funding output 推导的内容。

## 验证清单

1. Deploy TX 是否创建了 AMM 合约地址。
2. 初始流动性是否进入合约地址。
3. 合约是否进入 ready 状态。
4. Swap 调用是否生成预期 Result TX。
5. Result TX 是否把输出资产发给用户。
6. 添加或移除流动性后，LP 份额和池子余额是否变化。
7. Explorer / Indexer / 钱包展示是否一致。

## 风险边界

1. 当前 AMM 模板合约仅用于测试网。
2. 池子价格由测试资产和测试流动性决定，不代表真实市场价格。
3. 测试网确认、索引和 Result TX 展示可能延迟。
4. 缺少 Result TX 或状态证据时，不应把页面余额当作最终结果。

**页面状态：开发中（In Development）**


# 部署 Launchpad

本文用于后续补充 Launchpad 模块部署、活动参数、资产分发、钱包授权和测试网验收流程。

**页面状态：规划中（Planning）**


# 部署智能合约模板限价单模块

LimitOrder 模板是当前聪网公开测试网上线的智能合约模板之一。它用于验证订单创建、成交、取消和退款如何在聪网智能合约框架中由 canonical Result TX 和 contract state root 表达。

注意：PWA `市场` 或 DEX 中的限价单是 L2 市场通道合约能力，不是本文讨论的智能合约模板 LimitOrder。本文讨论的模板 LimitOrder 只能从 PWA `工具 -> 智能合约` 入口交互。

## 当前状态

| 项目   | 状态                |
| ---- | ----------------- |
| 合约类型 | Template Contract |
| 模板   | LimitOrder        |
| 可用环境 | 聪网公开测试网           |
| 主网状态 | 暂未开放              |
| 费用资产 | 测试 GAS            |
| 交互入口 | PWA `工具 -> 智能合约`  |

## 基本流程

1. 部署者进入 PWA `工具 -> 智能合约`。
2. 选择交易资产和基础资产。
3. 部署限价单模板合约。
4. Maker 创建订单，把卖出资产转入合约地址。
5. Taker 填单，把支付资产转入合约地址。
6. 合约按价格和订单规则撮合。
7. Result TX 把成交资产分别转给买卖双方。
8. 未成交或取消部分通过 refund 退回。

## 调用动作

| 动作            | 说明                      |
| ------------- | ----------------------- |
| `swap` / 创建订单 | 挂买单或卖单，具体方向由输入资产和订单参数决定 |
| `refund`      | 取消挂单或取回可退资产             |

订单类型沿用模板协议定义：

| 类型  | 含义     |
| --- | ------ |
| `1` | 卖单     |
| `2` | 买单     |
| `3` | refund |

## 撮合规则摘要

1. 买单按价格从高到低排序。
2. 卖单按价格从低到高排序。
3. 同价格按区块顺序、交易顺序和 item id 排序。
4. 只有买价大于或等于卖价时成交。
5. 成交价使用卖单价格。
6. 每次撮合生成买家资产转移和卖家聪转移，两笔 transfer 位于同一个 Result TX。
7. 买单未使用的聪退回买家。
8. 卖单剩余资产不足以继续成交时，剩余资产退回卖家。

## 验证清单

1. Deploy TX 是否创建限价单合约地址。
2. 创建订单交易是否把卖出资产转入合约地址。
3. 订单是否进入 open 状态。
4. 填单交易是否转入正确支付资产。
5. Result TX 是否按撮合规则分配资产。
6. refund 是否只能取消调用者自己的未完成挂单。
7. 订单状态、Result TX 和钱包余额是否一致。

## 风险边界

1. 当前限价单模板合约仅用于测试网。
2. 测试网订单、价格和资产没有主网价值。
3. 订单状态需要结合钱包、Explorer 和 Indexer 证据判断。
4. 网络错误或页面延迟时，不要重复提交相同价值移动，先查 txid 和合约状态。

**页面状态：开发中（In Development）**


# 运行核心节点、Indexer 和 Explorer

本文用于基础设施团队启动聪网节点、Indexer、Explorer、RPC 和监控服务。当前先定义路径，后续补充完整命令和配置。

## 你可以运行什么

1. SatoshiNet Core Node。
2. BTC L1 Indexer。
3. SatoshiNet L2 Indexer。
4. Explorer。
5. RPC / API 网关。
6. 监控和告警。

## 操作前准备

1. 服务器和持久化磁盘。
2. 网络端口和域名。
3. BTC L1 节点或可信数据源。
4. SatoshiNet 节点配置。
5. 数据备份和监控方案。

## 推荐步骤

1. 阅读 [SatoshiNet 协议概览](/xie-yi-yu-an-quan/satoshinet/satoshinet)。
2. 阅读 [API 源码地图](/kai-fa-zhe-zhong-xin/api-source-map)。
3. 先在测试网启动节点或 Indexer。
4. 验证高度同步、交易查询、资产查询和错误处理。
5. 为钱包、DEX 或 Agent 提供只读 API。
6. 加入监控和告警。

## 验收标准

1. 节点高度正常同步。
2. L1/L2 Indexer 能查询交易、地址、UTXO 和资产。
3. Explorer 能通过 txid、address、asset 查询。
4. API 能表达 pending、not found、reorg、unindexed 等状态。
5. 服务重启后能恢复。

**页面状态：规划中（Planning）**


# 集成 Wallet SDK

本文用于后续补充 Wallet SDK 的安装、初始化、资产查询、签名授权、PWA adapter 和 DApp 集成示例。

**页面状态：规划中（Planning）**


# 搭建白标 DEX

本文用于后续补充白标 DEX 的模块选择、前端配置、后台配置、Indexer / Explorer / 钱包接入、测试网验收和上线检查。

**页面状态：规划中（Planning）**


# 构建 SatoshiNet AI Agent

本文面向 AI Agent 开发者。目标是让 Agent 能读取聪网文档、调用钱包 adapter、验证资产安全，并逐步扩展到 Community Builder Agent。

## 两条路径

| 路径                      | 目标                                             |
| ----------------------- | ---------------------------------------------- |
| Agent Wallet & Safety   | 帮用户安全操作钱包、STP 通道和资产跨层流动                        |
| Community Builder Agent | 帮 BTC 社区设计和部署 DEX、DAO、Indexer、Explorer、钱包和合约模块 |

## Agent Wallet 最小流程

1. 用户安装 SAT20 PWA Wallet。
2. 用户在 PWA 内创建或导入钱包。
3. Agent 安装 SAT20 Agent skill。
4. Agent 调用 `wallet.status`。
5. Agent 调用 `stp.status`。
6. Agent 调用 `stp.safety_snapshot`。
7. Agent 只在 `READY_SAFE` 时发起价值移动。
8. PWA 钱包展示授权弹窗。
9. Agent 轮询 `stp.transaction`。
10. Agent 返回 txid、状态和验证链接。

## Community Builder Agent 最小流程

1. 用户描述社区目标。
2. Agent 选择 DEX、DAO、Indexer、Explorer、钱包等模块。
3. Agent 生成配置草案。
4. 用户确认关键参数。
5. Agent 生成测试网部署计划。
6. 部署工具执行，钱包或多签完成授权。
7. Agent 收集 Explorer、Indexer 和合约证据。
8. Agent 生成社区上线检查报告。

## 当前需要补齐

1. 模块参数 JSON Schema。
2. 合约模板机器可读描述。
3. 部署工具接口。
4. 错误码和下一步建议。
5. 测试网案例和示例输出。

**页面状态：开发中（In Development）**


# 合约模板目录

本文整理聪网智能合约相关模板、运行时和测试网入口。更详细的协议规则见 [智能合约协议](/xie-yi-yu-an-quan/smart-contracts/contracts)。

## 当前状态矩阵

| 类型                        | 状态          | 测试网入口                                                                    | 说明                                                        |
| ------------------------- | ----------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| Agent / Prediction 合约     | 已实现 / 测试中   | [Prediction 合约测试](/shi-yong-cong-wang/prediction-contract)               | 当前公开测试网优先验证场景                                             |
| 模板合约：AMM                  | 已实现 / 测试网迭代 | PWA `工具 -> 智能合约`，[部署 AMM 池](/kai-fa-zhe-zhong-xin/amm-pool-quickstart)   | 智能合约模板测试能力，不是市场 AMM                                       |
| 模板合约：限价单                  | 已实现 / 测试网迭代 | PWA `工具 -> 智能合约`，[部署限价单模块](/kai-fa-zhe-zhong-xin/limit-order-quickstart) | 智能合约模板测试能力，不是市场限价单                                        |
| 模板合约：资产兑换                 | 已实现 / 测试网迭代 | 待补充                                                                      | 面向固定规则资产兑换场景                                              |
| 模板合约：自动支付                 | 已实现 / 测试网迭代 | 待补充                                                                      | `autopay.tc`，按区块高度向指定地址支付固定或线性费用                          |
| EVM Runtime               | 已实现 / 测试网迭代 | [EVM 开发者预览](/kai-fa-zhe-zhong-xin/evm-quickstart)                        | 复用 Solidity / EVM 开发生态；调用使用 ABI calldata，资产结算仍走聪网 UTXO 模型 |
| EVM 样本：ConstantProductAMM | 已实现 / 测试中   | PWA `工具 -> 智能合约`，[EVM 样本合约](/kai-fa-zhe-zhong-xin/evm-sample-contracts)  | Solidity AMM 标准样本，不是市场 AMM                                |
| EVM 样本：LimitOrderBook     | 已实现 / 测试中   | PWA `工具 -> 智能合约`，[EVM 样本合约](/kai-fa-zhe-zhong-xin/evm-sample-contracts)  | Solidity 限价单标准样本，不是市场限价单                                  |

## 模板文档应包含

每个模板合约后续应补齐：

1. 合约类型和模板名称。
2. 部署参数。
3. 调用接口。
4. 输入资产规则。
5. Result TX 输出规则。
6. 权限边界。
7. 费用和 GAS。
8. Explorer / Indexer 验证方法。
9. 测试网合约地址或示例 txid。
10. 已知限制。

## 当前优先级

1. Prediction 合约：补齐用户测试、部署者 Quickstart 和测试网证据。
2. AMM 模板合约：补齐部署、swap、add liquidity、remove liquidity 和验证流程。
3. 限价单模板合约：补齐挂单、成交、取消和 Result TX 验证流程。
4. 自动支付模板合约：补齐部署、funding、按区块支付、close 和 Result TX 验证流程。
5. EVM 样本合约：补齐 `ConstantProductAMM` 和 `LimitOrderBook` 的测试网地址、txid、calldata 生成记录和 Explorer 验证记录。
6. EVM Runtime：补齐 RPC、Chain ID、示例仓库、Solidity 部署流程、estimate 流程和 ABI calldata 调用流程。

**页面状态：规划中（Planning）**


# API 源码地图

SAT20 当前仍在快速演进，接口字段、错误码和测试网能力会随 STP、indexer、聪网节点和钱包适配器一起变化。现阶段 API 文档采用 source-first 方式维护：先明确接口域、权威代码入口、稳定性等级和接入边界；等接口进入稳定期后，再沉淀 OpenAPI、Swagger 或 SDK 文档。

旧的 ORDX indexer Swagger 只覆盖早期部分接口，不能代表当前 SAT20 / 聪网完整接口体系。新接入必须以当前 `v3` 路由、handler、源码模型和实际运行接口返回为准。本页直接链接到 GitHub 源码，作为当前最可靠的接口入口。

## 接口域

| 接口域                                 | 负责项目                                                                                                                                                               | 面向对象                            | 当前文档策略                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------- |
| BTC L1 Indexer API                  | [`indexer`](https://github.com/sat20-labs/indexer)                                                                                                                 | 钱包、交易平台、浏览器、STP 客户端、Agent       | 以 Gin router、handler 和 wire model 为准                |
| SatoshiNet Node RPC                 | [`satoshinet`](https://github.com/sat20-labs/satoshinet)                                                                                                           | 节点运维、矿工、钱包、合约工具                 | 以 JSON-RPC command、handler 和 help registry 为准       |
| SatoshiNet L2 Indexer API           | [`satoshinet/indexer`](https://github.com/sat20-labs/satoshinet/tree/main/indexer)                                                                                 | 钱包、交易平台、浏览器、STP 客户端、Agent       | 以 L2 indexer router、handler 和 model 为准              |
| SAT20 Wallet WASM / PWA Adapter API | [`sat20wallet`](https://github.com/sat20-labs/sat20wallet)                                                                                                         | 钱包 UI、DApp、AI Agent、PWA adapter | 以 WASM wrapper、PWA bridge、Agent adapter contract 为准 |
| STP Agent Adapter API               | [`docs`](https://github.com/sat20-labs/docs) + [`sat20wallet`](https://github.com/sat20-labs/sat20wallet) + [`transcend`](https://github.com/sat20-labs/transcend) | AI Agent 和第三方 STP 客户端           | 以 `sat20-agent-wallet` skill 契约和实现 adapter 为准       |

## 稳定性等级

| 等级                  | 含义                 | 接入建议          |
| ------------------- | ------------------ | ------------- |
| Public Stable       | 对外稳定接口，字段变化需要兼容    | 可用于生产接入       |
| Public Experimental | 可用于测试网和早期集成，字段可能变化 | 接入方需要保留兼容层    |
| Internal            | 内部模块接口，不承诺外部兼容     | 不建议第三方直接依赖    |
| Testnet Only        | 只在测试网可用，主网必须拒绝     | 仅用于演练、验证和故障注入 |
| Deprecated          | 历史接口或过时文档          | 不作为新接入依据      |

## BTC L1 Indexer API

BTC L1 indexer 负责解析 BTC 主网上的 UTXO、sat range、Ordinals、Runes、BRC20、ORDX、mempool、确认数和 reorg 状态。它是钱包、交易平台、STP 和 AI Agent 判断 L1 资产事实的入口。

权威源码入口：

| 内容                            | GitHub 源码                                                                                                                                                                                                                                                                                                                        |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 服务启动与 RPC 初始化                 | [`main.go`](https://github.com/sat20-labs/indexer/blob/main/main.go)                                                                                                                                                                                                                                                             |
| Gin 总路由与 Swagger 挂载           | [`rpcserver/router.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/router.go)                                                                                                                                                                                                                                     |
| 基础接口 router / handler         | [`rpcserver/base/router.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/base/router.go), [`rpcserver/base/handler.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/base/handler.go)                                                                                                                 |
| ORDX / 多资产接口 router / handler | [`rpcserver/ordx/router.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/ordx/router.go), [`rpcserver/ordx/handler.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/ordx/handler.go), [`rpcserver/ordx/handler_v3.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/ordx/handler_v3.go) |
| Ordinals 内容接口                 | [`rpcserver/ord/router.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/ord/router.go), [`rpcserver/ord/handler.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/ord/handler.go)                                                                                                                     |
| BTC 节点代理接口                    | [`rpcserver/bitcoind/router.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/bitcoind/router.go), [`rpcserver/bitcoind/handler.go`](https://github.com/sat20-labs/indexer/blob/main/rpcserver/bitcoind/handler.go)                                                                                                 |
| 对外响应模型                        | [`rpcserver/wire/`](https://github.com/sat20-labs/indexer/tree/main/rpcserver/wire)                                                                                                                                                                                                                                              |
| indexer 管理与协议处理               | [`indexer/indexermgr.go`](https://github.com/sat20-labs/indexer/blob/main/indexer/indexermgr.go), [`indexer/handle.go`](https://github.com/sat20-labs/indexer/blob/main/indexer/handle.go)                                                                                                                                       |
| ORDX 协议处理                     | [`indexer/ft/`](https://github.com/sat20-labs/indexer/tree/main/indexer/ft), [`indexer/nft/`](https://github.com/sat20-labs/indexer/tree/main/indexer/nft), [`indexer/ns/`](https://github.com/sat20-labs/indexer/tree/main/indexer/ns)                                                                                          |
| Runes / BRC20 处理              | [`indexer/runes/`](https://github.com/sat20-labs/indexer/tree/main/indexer/runes), [`indexer/brc20/`](https://github.com/sat20-labs/indexer/tree/main/indexer/brc20)                                                                                                                                                             |

接入重点：

1. 查询地址 UTXO 和单个 outpoint 的资产详情。
2. 查询资产协议状态、有效性和确认数。
3. 区分 mempool、已确认、未索引、reorg 和已花费状态。
4. 对 BRC20 transfer、Runes、ORDX、Ordinals 分别按协议规则解释。
5. 不把单个余额字段当成资产安全证明。

## SatoshiNet Node RPC

SatoshiNet 节点 RPC 继承 btcd 风格 JSON-RPC，同时扩展聪网交易、资产、合约、挖矿和网络能力。它服务节点运维、钱包、矿工、合约工具和调试工具。

权威源码入口：

| 内容                         | GitHub 源码                                                                                                                                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 节点启动与 RPC server 启动        | [`btcd.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcd.go), [`server.go`](https://github.com/sat20-labs/satoshinet/blob/main/server.go)                                                                       |
| JSON-RPC server            | [`rpcserver.go`](https://github.com/sat20-labs/satoshinet/blob/main/rpcserver.go)                                                                                                                                          |
| RPC handler adapter        | [`rpcadapters.go`](https://github.com/sat20-labs/satoshinet/blob/main/rpcadapters.go)                                                                                                                                      |
| WebSocket RPC              | [`rpcwebsocket.go`](https://github.com/sat20-labs/satoshinet/blob/main/rpcwebsocket.go)                                                                                                                                    |
| RPC help / result registry | [`rpcserverhelp.go`](https://github.com/sat20-labs/satoshinet/blob/main/rpcserverhelp.go)                                                                                                                                  |
| JSON-RPC command 注册与解析     | [`btcjson/register.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/register.go), [`btcjson/cmdparse.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/cmdparse.go)                           |
| 链节点命令与结果                   | [`btcjson/chainsvrcmds.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/chainsvrcmds.go), [`btcjson/chainsvrresults.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/chainsvrresults.go)     |
| btcd 扩展命令与结果               | [`btcjson/btcdextcmds.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/btcdextcmds.go), [`btcjson/btcdextresults.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/btcdextresults.go)         |
| 钱包相关命令模型                   | [`btcjson/walletsvrcmds.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/walletsvrcmds.go), [`btcjson/walletsvrresults.go`](https://github.com/sat20-labs/satoshinet/blob/main/btcjson/walletsvrresults.go) |
| 合约执行与结果                    | [`contract/`](https://github.com/sat20-labs/satoshinet/tree/main/contract)                                                                                                                                                 |
| POS 挖矿                     | [`mining/posminer/`](https://github.com/sat20-labs/satoshinet/tree/main/mining/posminer)                                                                                                                                   |

接入重点：

1. 区分继承自 btcd 的节点 RPC 与 SAT20 / SatoshiNet 扩展 RPC。
2. 合约、资产、挖矿相关接口以当前 command / result struct 为准。
3. 节点 RPC 不替代 indexer；资产事实仍需要 L1/L2 indexer 交叉验证。

## SatoshiNet L2 Indexer API

SatoshiNet L2 indexer 集成在聪网节点体系中，负责解析 L2 UTXO、ascend、descend、通道、合约、Core Node 状态和资产状态。它是 STP 操作后验证 L2 资产事实的入口。

权威源码入口：

| 内容                                  | GitHub 源码                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| L2 indexer 启动                       | [`indexer/main.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/main.go)                                                                                                                                                                                                                                                                                                           |
| L2 indexer 总路由                      | [`indexer/rpcserver/router.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/rpcserver/router.go)                                                                                                                                                                                                                                                                                   |
| SatoshiNet 查询 router / handler      | [`indexer/rpcserver/satoshinet/router.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/rpcserver/satoshinet/router.go), [`indexer/rpcserver/satoshinet/handler.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/rpcserver/satoshinet/handler.go)                                                                                                                    |
| indexer 查询 router / handler / model | [`indexer/rpcserver/indexer/router.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/rpcserver/indexer/router.go), [`indexer/rpcserver/indexer/handler.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/rpcserver/indexer/handler.go), [`indexer/rpcserver/indexer/model.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/rpcserver/indexer/model.go) |
| L2 indexer 管理器                      | [`indexer/indexer/indexermgr.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/indexer/indexermgr.go)                                                                                                                                                                                                                                                                               |
| L2 交易处理                             | [`indexer/indexer/handle.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/indexer/handle.go)                                                                                                                                                                                                                                                                                       |
| ascend / descend / STP 相关解析         | [`indexer/indexer/base/transcend.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/indexer/base/transcend.go), [`indexer/indexer/stp/transcend.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/indexer/stp/transcend.go)                                                                                                                                            |
| channel 状态索引                        | [`indexer/indexer/base/channel_state.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/indexer/base/channel_state.go)                                                                                                                                                                                                                                                               |
| 合约索引                                | [`indexer/indexer/contract_index.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/indexer/contract_index.go), [`indexer/indexer/contract/indexer.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/indexer/contract/indexer.go)                                                                                                                                      |
| L2 RPC client                       | [`indexer/share/satsnet_rpc/rpc.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/share/satsnet_rpc/rpc.go), [`indexer/share/satsnet_rpc/rpcclient.go`](https://github.com/sat20-labs/satoshinet/blob/main/indexer/share/satsnet_rpc/rpcclient.go)                                                                                                                                  |

接入重点：

1. 查询 L2 UTXO、资产余额和可花费状态。
2. 查询 ascend / descend 与 BTC L1 txid、outpoint 的对应关系。
3. 查询通道地址 ledger，用于 rebuild、expand 和异常恢复。
4. 查询合约执行结果和合约状态。
5. 区分 pending、confirmed、not indexed 和 reorg / rollback 后状态。

## SAT20 Wallet WASM / PWA Adapter API

SAT20 Wallet 负责私钥、助记词、签名、资产发送、用户授权、PWA 钱包状态和 STP adapter 调用。AI Agent 不直接接触私钥，而是通过 PWA adapter 或本地受控 adapter 发起操作。

权威源码入口：

| 内容                  | GitHub 源码                                                                                                                                                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Go WASM 入口          | [`sdk/wasm/main.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wasm/main.go)                                                                                                                                                                                           |
| 钱包核心管理              | [`sdk/wallet/manager.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/manager.go), [`sdk/wallet/wallet.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/wallet.go)                                                                             |
| 钱包基础接口              | [`sdk/wallet/interface.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/interface.go)                                                                                                                                                                             |
| 普通资产发送              | [`sdk/wallet/interface_send.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/interface_send.go), [`sdk/wallet/interface_send2.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/interface_send2.go)                                             |
| PSBT / 签名接口         | [`sdk/wallet/interface_psbt.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/interface_psbt.go), [`sdk/wallet/sign.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/sign.go)                                                                   |
| 合约客户端接口             | [`sdk/wallet/interface_contract_client.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/interface_contract_client.go), [`sdk/wallet/interface_contract_unified.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/interface_contract_unified.go) |
| STP / 通道钱包能力        | [`sdk/wallet/channelwallet.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/channelwallet.go), [`sdk/wallet/chaininfo_satsnet.go`](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wallet/chaininfo_satsnet.go)                                           |
| PWA WASM wrapper    | [`pwa/utils/sat20.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/utils/sat20.ts), [`pwa/utils/stp.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/utils/stp.ts)                                                                                           |
| PWA Agent adapter   | [`pwa/composables/usePwaAgentAdapter.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/composables/usePwaAgentAdapter.ts)                                                                                                                                                 |
| PWA DApp Connect 类型 | [`pwa/types/sat20-dapp-connect.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/types/sat20-dapp-connect.ts)                                                                                                                                                             |
| PWA DApp bridge     | [`pwa/composables/usePwaDappBridge.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/composables/usePwaDappBridge.ts)                                                                                                                                                     |
| 授权弹窗与授权状态           | [`pwa/components/approve/ApproveAgentOperation.vue`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/components/approve/ApproveAgentOperation.vue), [`pwa/store/approve.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/store/approve.ts)                       |
| L1 / L2 资产 hooks    | [`pwa/composables/hooks/useL1Assets.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/composables/hooks/useL1Assets.ts), [`pwa/composables/hooks/useL2Assets.ts`](https://github.com/sat20-labs/sat20wallet/blob/main/pwa/composables/hooks/useL2Assets.ts)               |

接入重点：

1. 钱包创建、导入、导出助记词、修改密码必须由钱包授权边界处理。
2. `wallet.*` 和 `stp.*` agent-facing 操作只返回授权后的结果和可验证证据。
3. STP 价值移动前后需要 `stp.safety_snapshot`、`stp.transaction`、commitment export 和 punish coverage。
4. PWA adapter 是面向普通用户和 AI Agent 的推荐接入层；底层 WASM 函数不是 Agent 直接操作边界。

## STP Agent Adapter API

STP Agent Adapter 是面向 AI Agent 的语言无关 JSON 契约。它不替代钱包，也不替代 Core Node；它定义 Agent 如何请求钱包执行操作、如何读取安全证据、如何在网络结果未知时恢复。

权威文档与源码入口：

| 内容                       | GitHub 源码                                                                                                                                                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAT20 Agent Wallet 安装与使用 | [`ai/sat20-agent-wallet/readme.md`](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/sat20-agent-wallet)                                                                                                                       |
| 互操作技能规范                  | [`ai/sat20-agent-wallet/interoperability.md`](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/interoperability)                                                                                                               |
| Adapter contract         | [`ai/sat20-agent-wallet/skills/sat20-agent-wallet/references/adapter-contract.md`](https://github.com/sat20-labs/docs/blob/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/references/adapter-contract.md)                   |
| 操作 playbooks             | [`ai/sat20-agent-wallet/skills/sat20-agent-wallet/references/operation-playbooks.md`](https://github.com/sat20-labs/docs/blob/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/references/operation-playbooks.md)             |
| PWA WASM adapter 说明      | [`ai/sat20-agent-wallet/skills/sat20-agent-wallet/references/pwa-wasm-adapter.md`](https://github.com/sat20-labs/docs/blob/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/references/pwa-wasm-adapter.md)                   |
| 通用转发脚本                   | [`ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_adapter.py`](https://github.com/sat20-labs/docs/blob/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_adapter.py)                                   |
| transcend RPC adapter    | [`ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_transcend_rpc_adapter.py`](https://github.com/sat20-labs/docs/blob/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_transcend_rpc_adapter.py)       |
| workspace wallet adapter | [`ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_workspace_wallet_adapter.py`](https://github.com/sat20-labs/docs/blob/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_workspace_wallet_adapter.py) |

接入重点：

1. Agent 只表达目标、资产、金额、方向和安全检查要求。
2. 资产输入、fee 输入、BRC20 transfer inscription、交易包和签名由 adapter 内部处理。
3. 主网价值移动必须经过用户授权。
4. 测试网 fault / punish drill 接口只能在测试网使用。

## 文档演进

当前 API 文档以源码地图为准。后续接口稳定后，文档可以逐步补齐：

1. 关键 Public Stable 接口的请求/响应样例。
2. 标准错误码和状态机。
3. OpenAPI / Swagger，只覆盖稳定公开接口。
4. 多语言 SDK 或 client generator。
5. Agent 可复核的 explorer / indexer URL schema。


# Indexer 接入与资产事实层

本文面向钱包、交易平台、浏览器、STP 客户端、AI Agent 和基础设施团队，说明如何理解 SAT20 indexer 的角色。

## Indexer 是什么

Indexer 是 BTC L1 与聪网 L2 的资产事实层。它不保管资产，不替用户签名，也不决定资产归属；它根据链上交易和协议规则，计算并提供可查询的资产状态。

SAT20 生态至少需要两类 indexer：

| 类型                    | 主要数据                                                                 |
| --------------------- | -------------------------------------------------------------------- |
| BTC L1 Indexer        | BTC UTXO、sat range、Ordinals、Runes、BRC20、ORDX、铭文、mempool、确认数、reorg 状态 |
| SatoshiNet L2 Indexer | 聪网 UTXO、ascend、descend、通道、合约、交易执行、资产状态                               |

## 谁需要接入

| 角色       | 接入目的                                                 |
| -------- | ---------------------------------------------------- |
| 钱包       | 展示资产、选择 UTXO、验证跨层操作结果                                |
| STP 客户端  | 判断 splicing-in/out、open/close、lock/unlock 的资产输入和链上状态 |
| 交易平台     | 充值、提现、对账、风控和异常恢复                                     |
| 区块浏览器    | 展示 L1/L2 交易、资产、通道和合约状态                               |
| AI Agent | 在价值移动前独立验证资产证据和安全边界                                  |

## 最低接入能力

一个合格客户端至少需要查询：

1. 地址 UTXO 列表。
2. 单个 UTXO 的资产详情。
3. 交易确认数、mempool 状态和是否被花费。
4. Ordinals、Runes、BRC20、ORDX 等协议资产状态。
5. L1 ascend / descend 相关交易。
6. L2 地址余额、UTXO、通道和合约交易。
7. reorg 或暂未索引时的明确错误状态。

对 STP 来说，关键不是“余额是多少”，而是“资产证据链是否完整”：L1 UTXO、L1 交易确认、ascend / descend 事件、L2 UTXO、通道承诺状态和钱包本地状态必须能互相解释。

## 接入原则

1. 单个余额字段不是资产安全证明。
2. 对 BTC L1 资产，必须关注 txid、vout、资产协议、确认数和花费状态。
3. 对 BRC20 transfer、Runes、ORDX、Ordinals 等资产，必须按协议规则判断有效性。
4. 对 STP 操作，必须能区分 L1 已确认、L2 已 ascend、L2 可花费、通道已更新这几个状态。
5. 对 mempool、网络错误、EOF、未索引和 reorg，客户端应返回明确状态，不应默认失败或默认成功。
6. 交易平台和 Agent 应保留可复核证据：txid、vout、asset、amount、height、confirmations、indexer source 和查询时间。

## 与 STP 的关系

STP 负责资产控制权，indexer 负责资产事实。

当用户发起 splicing-in 时，indexer 帮助客户端确认目标 UTXO 是否携带资产、资产是否有效、交易是否确认；STP 负责把该资产纳入通道并在聪网上生成对应状态。

当用户发起 splicing-out 或 close 时，STP 负责构造退出路径；indexer 帮助钱包和 Agent 确认 L2 descend 与 BTC L1 输出是否对应，资产是否已经回到用户可控制地址。

## 分布式 Indexer 方向

当前接入可以从官方 API 开始，但 indexer 的目标不是形成单点服务。它应逐步成为多方可独立运行、可交叉验证的资产事实网络。

L2 indexer 已经集成在聪网节点中。运行聪网节点的团队会随节点维护自己的 L2 UTXO、ascend、descend、通道、合约和交易状态，因此 L2 indexer 天然随着聪网节点网络分布。

L1 indexer 服务 BTC 主网资产事实。聪网 Core Node 要求配置并依赖自己的 L1 indexer，用来验证 L1 UTXO、资产协议事件、确认状态和跨层操作。也就是说，Core Node 网络本身会推动 L1 indexer 的事实分布式部署。

分布式 indexer 的建设重点包括：

1. 规则可公开复现。
2. 数据结果可交叉验证。
3. reorg、mempool 和异常状态可标准化表达。
4. 交易平台、钱包和 Agent 可以配置多个数据源。
5. 关键资产状态可以通过证明材料而不是单一 API 响应来解释。
6. Core Node、钱包、交易平台和浏览器可以独立运行或选择可信的 L1/L2 indexer。

这会让 BTC 主网上多协议资产拥有更安全、更统一的表达方式，也会让聪网成为更可信的比特币原生扩展网络。


# 交易平台与钱包接入

交易平台和钱包是聪网生态的重要入口。它们需要的不只是转账接口，还需要能解释资产处于 BTC L1、通道、聪网个人地址、合约或 pending 状态中的哪一种。

对交易平台和钱包来说，indexer 是资产事实层。充值、提现、splicing、unlock、lock、余额展示和风控都必须建立在 L1/L2 indexer 可复核的 txid、vout、资产协议、确认数和通道状态之上。

## 接入目标

| 角色      | 目标                          |
| ------- | --------------------------- |
| 钱包      | 管理私钥、授权、签名、通道状态和用户安全提示      |
| 交易平台    | 支持充值、提现、资产识别、确认数和异常处理       |
| Indexer | 提供 L1/L2 资产、交易、UTXO、通道和合约状态 |
| Agent   | 读取证据，解释风险，调用钱包 adapter      |

## 钱包必须保护什么

钱包必须保护：

1. 助记词和私钥。
2. 通道数据库。
3. 最新承诺交易。
4. 已撤销状态的惩罚材料。
5. 未完成 reservation。
6. 用户授权记录。

Agent 不直接接触这些秘密材料。

## 交易平台必须理解什么

交易平台接入聪网时，应区分：

1. BTC L1 确认。
2. 聪网 L2 确认。
3. STP 通道状态。
4. anchor / deAnchor 状态。
5. 资产是否可花费。
6. 是否存在 pending 操作。

如果只看余额，不看状态，容易在跨层过程中产生错误判断。

如果只看单个 indexer 响应，不看 txid、vout、确认数、reorg、mempool 和跨层对应关系，也容易产生错误判断。关键资产移动应保留可复核证据。

## 推荐接口

1. L1 / L2 地址 summary。
2. 交易详情。
3. UTXO 资产详情。
4. channel ledger。
5. anchor / deAnchor 记录。
6. STP transaction / reservation 查询。
7. safety snapshot。
8. reorg / mempool / not indexed 状态。

后续交易平台接入文档会在此基础上继续拆分为充值、提现、风控、对账和异常恢复章节。


# 运行网络：节点与基础设施


# 概述

开放网络需要第三方能够运行节点、Indexer、Explorer、RPC 和监控服务。运行网络不是边缘角色，而是聪网长期去中心化、安全性和可用性的基础。

## 角色

| 角色             | 主要职责                                  |
| -------------- | ------------------------------------- |
| 挖矿节点           | 提供出块、交易排序和合约执行                        |
| 核心节点           | 覆盖挖矿节点全部功能，并额外提供 STP 服务，承担更高在线和通道安全责任 |
| L1 Indexer     | 索引 BTC L1 多协议资产事实                     |
| L2 Indexer     | 索引聪网交易、UTXO、通道、合约和跨层状态                |
| Explorer / RPC | 为用户、钱包、交易平台、Agent 和开发者提供可验证访问         |
| 监控与运维          | 提供备份、告警、升级和 SLA 能力                    |

## 当前重点

1. 明确挖矿节点和核心节点的职责层级：核心节点包含挖矿节点能力，并额外承担 STP 服务。
2. 明确 GAS 质押、费用和处罚仍有哪些设计中参数。
3. 让第三方能够在测试网运行节点、Indexer 或 Explorer。
4. 让钱包、DEX、Agent 和交易平台能使用独立基础设施验证状态。
5. 公布哪些组件当前由 SAT20 Labs 运行，哪些可以由第三方运行。

**页面状态：开发中（In Development）**


# 挖矿节点

挖矿节点负责聪网的出块、交易排序和合约执行。它是网络执行能力和费用流的基础角色。

## 需要回答的问题

1. 挖矿节点做什么。
2. 如何参与出块。
3. 如何选择出块者。
4. GAS 质押的作用。
5. 节点可以获得哪些实际网络费用。
6. 服务器、带宽、在线率和安全要求。
7. 如何加入测试网。
8. 如何升级和退出。
9. 哪些处罚规则仍在设计中。

## 当前边界

节点费用来自实际网络服务，不是固定收益产品。完整质押门槛、处罚规则、解除质押时间和准入流程仍在设计中。

**页面状态：设计中（Design in Progress）**


# 核心节点

核心节点覆盖挖矿节点的全部功能，同时额外提供 STP 服务，连接用户钱包与聪网执行层。它承担更高的在线要求、通道状态责任和资产跨层服务责任。

## 与挖矿节点的关系

| 维度            | 挖矿节点         | 核心节点                             |
| ------------- | ------------ | -------------------------------- |
| 基础能力          | 出块、排序、执行     | 包含挖矿节点全部能力                       |
| 额外职责          | 不提供 STP 通道服务 | STP 服务、通道状态、跨层资产控制               |
| 资产安全责任        | 网络执行与共识相关    | 同时承担网络执行责任和用户通道、承诺交易、异常恢复相关责任    |
| L1 Indexer 依赖 | 需要理解链上事实     | 需要更稳定地访问 L1 Indexer，并用于 STP 跨层验证 |
| 质押要求          | 计划使用 GAS 质押  | 计划有更高要求，参数仍在设计中                  |

## 需要补充

1. STP 服务费和网络费用的边界。
2. 用户通道失败时的恢复边界。
3. 公开测试网准入流程。
4. 节点离线、拒绝服务或状态异常时的处理方式。

**页面状态：设计中（Design in Progress）**


# L1 / L2 Indexer

Indexer 是聪网资产事实层。L1 Indexer 负责 BTC 主网多协议资产事实，L2 Indexer 负责聪网交易、UTXO、通道、合约和跨层状态。

## 运行价值

1. 为钱包和交易平台提供资产查询。
2. 为 Explorer 提供可视化数据。
3. 为 STP 和 Agent 提供跨层证据。
4. 为 DEX、DAO 和合约应用提供状态查询。
5. 通过多方运行降低单点依赖。

## 需要补充

1. L1 Indexer 部署要求。
2. L2 Indexer 部署要求。
3. 数据备份和 reorg 处理。
4. API 稳定性和错误码。
5. 多 indexer 交叉验证方式。

**页面状态：规划中（Planning）**


# Explorer / RPC

Explorer 和 RPC 是用户、开发者、钱包、交易平台和 Agent 验证聪网状态的公共入口。

## 需要提供的能力

1. 按 txid、address、asset、contract 查询。
2. 展示 BTC L1 与聪网 L2 的跨层证据。
3. 展示 STP 通道、commit height、ascend / descend 和 punish 证据。
4. 展示合约部署、调用和 Result TX。
5. 表达 pending、not found、reorg、unindexed 和 failed 等状态。

**页面状态：规划中（Planning）**


# 监控、备份与升级

节点和基础设施运行者需要可重复的监控、备份、升级和恢复流程。

## 需要覆盖

1. 节点高度、peer、mempool 和出块状态。
2. L1/L2 indexer 高度和 reorg 状态。
3. STP 通道和合约状态。
4. 数据目录、钱包目录和关键数据库备份。
5. 版本升级、回滚和兼容性检查。
6. 告警、日志和公开状态页。

**页面状态：规划中（Planning）**


# 节点质押与退出

挖矿节点和核心节点计划使用 GAS 作为质押资产。完整质押规则、解除质押时间、处罚参数和准入流程仍在设计中。

## 当前确定的表达边界

1. GAS 是网络费用与安全质押资产。
2. 节点根据实际提供的网络服务获得协议费用。
3. 不承诺固定收益或固定 APY。
4. 质押、处罚、退出和节点准入参数以未来正式协议和链上规则为准。

**页面状态：设计中（Design in Progress）**


# 去中心化路线

聪网的长期目标不是让所有社区和应用永久依赖 SAT20 Labs。第三方应能独立运行节点、Indexer、Explorer、钱包、DEX 和 DAO。

## 路线问题

1. 当前哪些组件由 SAT20 Labs 运行。
2. 第三方当前能运行什么。
3. 节点准入如何逐步开放。
4. Indexer 如何独立部署和交叉验证。
5. 如果 SAT20 Labs 停止运行，用户和社区还能做什么。
6. 哪些协议、工具和证据需要优先公开。

**页面状态：规划中（Planning）**


# 协议与安全


# SAT20 协议体系

SAT20 不是单一协议，而是一组围绕比特币原生资产建立的协议、索引、通道和执行环境。它的目标是让 BTC、Ordinals、Runes、BRC20、ORDX 等资产在保持用户控制权的前提下，进入一个更适合流通、合约和 AI Agent 自动化操作的网络。

## 四个基础层

| 层级         | 作用                                                     |
| ---------- | ------------------------------------------------------ |
| Indexer    | 将 BTC L1 和 SatoshiNet L2 上的交易解析为可查询、可复核的资产事实           |
| STP        | 用 RSMC 通道、承诺交易、撤销和惩罚机制，让资产进入、流通和退出聪网                   |
| SatoshiNet | 承载聪网交易、enUTXO、通道合约、智能合约和 GAS 经济                        |
| 通道合约       | 管理公共资产池，协调用户发起的 L1/L2 跨层动作                             |
| 资产发行协议     | BTC、Ordinals、Runes、BRC20、ORDX 等由 Indexer 统一解析和表达的资产协议族 |

这四层的关系可以概括为：

1. BTC、Ordinals、Runes、BRC20、ORDX 等协议定义或承载资产。
2. Indexer 把这些资产从链上交易中解析出来，形成统一资产事实。
3. STP 把资产纳入用户与 Core Node 共同控制的通道，并在聪网生成对应资产状态。
4. 通道合约作为公共设施，协调用户发起的 L1/L2 跨层动作和公共资产池状态。
5. SatoshiNet 让资产在 L2 上快速流通、进入智能合约、支付 GAS，并在需要时通过 STP 回到 BTC L1。

## 设计原则

SAT20 协议体系遵循以下原则：

1. 资产来自比特币主网。聪网不凭空创造与 BTC L1 无关的资产余额。
2. 用户保留退出能力。Core Node 失败或作恶时，用户仍应能依靠承诺交易、惩罚交易和强制关闭路径保护资产。
3. 资产事实可复核。钱包、交易平台、浏览器和 AI Agent 应能追溯每份资产的 L1/L2 证据。
4. 协议语言无关。STP 客户端、Indexer 客户端和合约工具都应能由任意开发语言实现。
5. 面向 Agent 可验证。协议结果不仅表现为余额变化，还提供 txid、UTXO、commit height、ascend/descend、punish coverage 等证据。

## 阅读顺序

如果你是协议实现者，建议按以下顺序阅读：

1. [Indexer：比特币资产事实层](/learn-li-jie-cong-wang/indexer)
2. [STP 技术白皮书](/xie-yi-yu-an-quan/stp/stp)
3. [SatoshiNet 协议概览](/xie-yi-yu-an-quan/satoshinet/satoshinet)
4. [通道合约](/xie-yi-yu-an-quan/channel-contracts/channel-contracts)
5. [资产发行协议](/xie-yi-yu-an-quan/indexer/asset-issuance)
6. [智能合约协议](/xie-yi-yu-an-quan/smart-contracts/contracts)

如果你是钱包、交易平台或 AI Agent 开发者，建议先读 [开发者中心](/kai-fa-zhe-zhong-xin/build)，再进入具体协议文档。


# Indexer


# 资产发行协议

比特币主网本身只原生理解 BTC 与 UTXO。Ordinals、Runes、BRC20、ORDX 等资产协议，都把资产语义写入 BTC 交易、脚本、铭文、sat range 或协议事件中。Indexer 的职责不是发明这些资产，而是把它们从链上事实中解析出来，形成统一、可查询、可复核的资产状态。

因此，资产发行协议应放在 Indexer 下面理解：它们是 Indexer 需要支持和统一表达的协议族。ORDX 是 SAT20 独自设计的聪绑定资产协议，但它不是唯一资产协议；聪网需要同时服务 BTC 主网上已经存在和未来出现的多种资产。

## Indexer 支持的主要资产类型

| 协议 / 资产类型 | 核心语义                                           | Indexer 需要表达什么                                              |
| --------- | ---------------------------------------------- | ----------------------------------------------------------- |
| BTC       | 比特币原生 UTXO 资产                                  | 地址 UTXO、金额、确认数、花费状态、mempool / reorg 状态                      |
| Ordinals  | 基于 sat 序号和 inscription 的数字对象                   | sat range、inscription、owner、所在 UTXO、转移历史                    |
| Runes     | BTC L1 上的同质化资产协议                               | etching、mint、transfer、余额、UTXO 归属和有效性                        |
| BRC20     | 基于 inscription 的 deploy / mint / transfer 资产协议 | ticker、deploy、mint、transfer inscription、有效/无效 transfer、地址余额 |
| ORDX      | SAT20 设计的聪绑定资产发行协议                             | ticker、deploy、mint、绑定聪、解绑、冻结、UTXO 归属和 sat range             |

STP 和 SatoshiNet 通过 Indexer 确认资产事实，而不是直接猜测资产。资产进入通道前，客户端必须先通过 L1 indexer 确认目标 UTXO 中的资产协议、数量、有效性和确认状态。资产进入聪网后，L2 indexer 继续追踪 ascend、descend、enUTXO、通道和合约状态。

## 统一表达原则

Indexer 对不同资产协议应尽量提供统一的查询语义：

1. 资产标识：协议、ticker / rune id / inscription id / asset name。
2. 资产数量：按协议精度表达，不能丢失 divisibility。
3. 承载位置：txid、vout、sat range、address、layer。
4. 有效性：协议事件是否有效，是否已被后续事件消费或失效。
5. 确认状态：mempool、confirmations、height、reorg 风险。
6. 跨层状态：是否已经 ascend 到聪网，是否已经 descend 回 BTC L1。

钱包、交易平台、STP 客户端和 AI Agent 都应基于这些字段做判断，而不是只依赖单个余额字段。

## ORDX 协议

ORDX 是 SAT20 体系中的聪绑定资产发行协议。它的核心思想是：资产不是独立存在的账户余额，而是绑定在可识别、可追踪的聪上。聪在哪里，资产就在哪里；聪属于谁，资产就属于谁。

### 核心属性

ORDX 资产继承聪的几个关键属性：

1. 聪不可凭空销毁，因此绑定在聪上的资产也不能在协议外随意消失。
2. 聪的序号使每一聪具备可识别性，资产可以绑定到特定聪或特定聪集合上。
3. 聪在 UTXO 中流动，资产也随 UTXO 流动。
4. 聪的非均质化让资产天然具备 SFT 属性。
5. 资产发行、铸造、解绑、冻结等状态都应由 indexer 从 BTC L1 交易中复算。

ORDX 与账户模型资产不同。钱包和交易平台不能只看地址余额，还必须理解承载资产的 UTXO、sat range、绑定数量和协议状态。

### 基础能力

ORDX 依赖两类基础能力：

1. 识别和跟踪聪：确定某个 UTXO 中包含哪些 sat range，某个聪当前位于哪里。
2. 在聪上写入和读取协议数据：通过铭文或 OP\_RETURN 表达 deploy、mint、unbind、freeze 等协议事件。

Indexer 是 ORDX 的事实计算层。它负责解析 BTC L1 交易，判断协议事件是否有效，并向钱包、浏览器、STP 客户端和交易平台提供可查询结果。

### Deploy

`deploy` 用于部署一个 ORDX ticker。

| 字段         | 必填 | 含义                                      |
| ---------- | -- | --------------------------------------- |
| `p`        | 是  | 协议名，固定为 `ordx`                          |
| `op`       | 是  | 指令，固定为 `deploy`                         |
| `tick`     | 是  | 资产名称；通常为 3 个或 5-16 个字符，4 字符名称为 BRC20 保留 |
| `lim`      | 否  | 单次 mint 上限，默认 `10000`；特殊 sat 资产默认 `1`   |
| `n`        | 否  | 每聪绑定的 token 数量，默认 `1`，最大 `65535`        |
| `selfmint` | 否  | 项目方或持有者自铸比例                             |
| `max`      | 否  | 最大供应量                                   |
| `block`    | 否  | 允许 mint 的高度区间                           |
| `attr`     | 否  | 对可绑定聪的属性要求                              |
| `des`      | 否  | 描述信息                                    |

示例：

```json
{
  "p": "ordx",
  "op": "deploy",
  "tick": "satoshi",
  "block": "830000-833144",
  "lim": "10000"
}
```

部署规则应至少包括：

1. ticker 名称未被使用。
2. 如果设置 `block`，deploy 确认高度必须早于 mint 起始高度足够区块。
3. 字段格式、数量上限、名称长度和属性条件必须通过 indexer 校验。

### Mint

`mint` 用于铸造已经部署的 ticker。

| 字段     | 必填 | 含义                               |
| ------ | -- | -------------------------------- |
| `p`    | 是  | 协议名，固定为 `ordx`                   |
| `op`   | 是  | 指令，固定为 `mint`                    |
| `tick` | 是  | 已部署资产名称                          |
| `amt`  | 否  | 本次 mint 数量，默认等于 `lim`，不能超过 `lim` |
| `sat`  | 否  | 当 deploy 设置 sat 属性要求时，指定满足条件的聪   |

示例：

```json
{
  "p": "ordx",
  "op": "mint",
  "tick": "satoshi"
}
```

Mint 校验应至少包括：

1. ticker 已经部署。
2. `amt` 不超过单次上限。
3. 总供应量不超过 `max`。
4. 如果有 `block`，mint 高度位于允许区间内。
5. 如果有 `selfmint`，按 selfmint 规则校验铸造权限和额度。
6. 如果有 `attr` 或 `sat`，目标聪满足稀有度、尾零或其他扩展条件。

## ORDX v2 指令

ORDX v2 在兼容旧版本的基础上，增加了更适合 L2 流通和受控资产场景的能力。

### 数据写入方式

v2 支持通过 OP\_RETURN 写入协议数据：

```
OP_RETURN | SAT20_MAGIC_NUMBER | CONTENT_TYPE | CONTENT
```

OP\_RETURN 让部分协议事件表达更简洁，也更便于 indexer 直接解析。

### Unbind

`unbind` 将指定 UTXO 输出中的某个 ORDX ticker 与聪解绑。该操作是永久的，只能由资产 owner 发起。

规则：

1. 输入包含需要解绑的目标 UTXO。
2. 输出指定目标 vout。
3. OP\_RETURN 内容指定 ticker 与 vout。
4. 该 vout 中指定 ticker 的资产全部解绑，其他资产类型不受影响。

### Freeze / Unfreeze

`freeze` 和 `unfreeze` 面向稳定币等受控资产场景，用于地址级权限控制。

规则：

1. 冻结目标是 `ticker + address + height`。
2. 冻结高度由指令声明，且指令确认高度必须与冻结高度接近。
3. 被冻结地址上该 ticker 的现有资产和后续流入资产都视为冻结资产。
4. 冻结资产不可作为该 ticker 的有效可转移资产使用。
5. 如果底层 BTC UTXO 被花费，冻结资产不会随输出转移，而是在协议层失效。
6. 解冻后，该地址上仍有效的绑定资产可以正常转移；已经因冻结花费而失效的资产不会恢复。

发起权限：

1. 只有满足协议规则的受控 ticker 才能被冻结或解冻。
2. 通常仅允许该 ticker 的当前 deploy owner 发起。

## 与 STP 和聪网的关系

资产进入聪网时，必须先由 L1 indexer 确认其协议类型、数量、有效性和所在 UTXO。STP splicing-in 只会让用户明确指定的一种资产进入聪网；如果一个 UTXO 同时携带多种资产，未指定资产不会被 ascend。

ORDX 必然绑定聪。进入聪网时，客户端必须根据资产数量和 `bindingSat` 计算需要多少聪。ORDX mint 结果中可能同时包含 ordinals NFT 与 ORDX ticker 资产；当前 STP 不把 `ordx:o` 类型资产 ascend 到聪网，客户端和 indexer 应把它作为不进入聪网的附带对象处理。

BRC20 和 Runes 在聪网上不需要绑定聪，但在 BTC L1 上仍受各自协议和比特币输出规则约束。STP 客户端和 Agent 不能把 L2 的 0 聪资产 UTXO 规则套用到 L1。

## 相关服务

ORDX 可以扩展出名字服务、KV 数据服务、SFT/NFT/FT/DID 等应用形态。但这些应用都应建立在同一个基础上：资产事实由 BTC L1 交易和 indexer 复算，资产控制权由 UTXO 所有权决定。


# STP


# STP 技术白皮书

STP（Satoshi Transcending Protocol）是连接比特币主网与聪网 SatoshiNet 的资产通道协议。它的目标不是建立托管桥，而是让用户把 BTC L1 上的资产纳入由用户和 Core Node 共同控制的通道，并在聪网上获得快速、低成本、可合约化的流动能力。

本文只描述协议语义，不绑定任何代码仓库、接口名称或开发语言。任何钱包、SDK、PWA、CLI 或 AI Agent 适配器，都可以依据本文实现 STP 客户端并接入兼容的 Core Node。

## 摘要

STP 的安全基础与闪电网络相同，来自 RSMC：2-of-2 通道、多版本承诺交易、撤销秘密、CSV 延迟和惩罚交易。用户不需要信任 Core Node 一定在线或诚实；用户需要持有最新承诺交易，并具备在 peer 广播旧状态时构造惩罚交易的能力。

STP 与传统闪电网络的区别在于：

1. STP 支持多资产：BTC、ORDX、Runes、BRC20 等 BTC L1 原生资产都可以进入通道。
2. STP 支持动态容量：通道可以通过 splicing-in、splicing-out、expand 和 lock-with-expand 调整资产集合。
3. STP 连接 SatoshiNet：资产进入聪网后可以在 L2 UTXO、合约和 GAS 经济中流通。
4. STP 依赖 indexer 作为资产事实层：L1 indexer 解析 BTC 主网资产，L2 indexer 解析聪网 ascend、descend、通道和合约状态。

SAT20 的资产基础应理解为 STP + Indexer。Indexer 告诉客户端资产是什么、在哪里、是否有效；STP 决定这些资产如何进入、流通、退出，以及用户如何在异常情况下保护控制权。

## 协议目标

STP 必须满足以下目标：

1. 用户最终控制权：通道资产由用户和 Core Node 共同控制，用户始终应持有可广播的最新承诺交易。
2. BTC L1 退出安全：Core Node 离线、拒绝服务或作恶时，用户可以通过强制关闭和后续清扫取回资产。
3. 旧状态惩罚：Core Node 广播旧承诺交易时，用户可以通过惩罚交易夺回违规输出。
4. 多资产一致性：白聪、ORDX、Runes、BRC20 等资产数量和协议规则在 L1、通道和 L2 之间保持一致。
5. 可复核资产事实：客户端必须通过 L1/L2 indexer 复核 UTXO、资产、ascend、descend、确认数和通道状态。
6. 语言无关互操作：客户端实现只需遵守消息、签名、交易、状态和恢复规则，不应依赖某个特定实现。

## 聪网节点角色

历史文档或接口中出现的 `STP Server`，在协议角色上应理解为 Core Node 对外提供的 STP 服务能力。聪网主要包括以下节点：

| 节点             | 职责                                                                          |
| -------------- | --------------------------------------------------------------------------- |
| Bootstrap Node | 辅助 Core Node 发现和准入                                                          |
| Core Node      | 覆盖 Mining Node 全部功能，并提供 STP 服务，与钱包建立私人通道，协签通道交易，维护服务侧通道状态，并运行或配置 L1 indexer |
| Mining Node    | 参与聪网出块，不提供 STP 通道服务                                                         |
| Wallet Client  | 用户钱包或客户端，连接 Core Node，持有私钥、通道状态、承诺交易和惩罚材料                                   |

普通用户连接 Core Node 打开私人通道，不需要质押资产。只有节点连接 Bootstrap Node 并准备以 Core Node 身份参与网络服务时，才涉及核心节点准入和质押要求。

## 通道模型

STP 通道是用户与 Core Node 之间的 2-of-2 资产控制关系。通道地址上的 BTC L1 UTXO 代表通道的链上控制边界；聪网中的 L2 状态代表通道资产在 SatoshiNet 中的流动状态。

一个通道至少包含：

| 对象                | 含义                                        |
| ----------------- | ----------------------------------------- |
| 通道地址              | 用户公钥与 Core Node 公钥生成的 2-of-2 地址           |
| Channel Point     | 当前承诺交易花费的 L1 通道 outpoint                  |
| 承诺高度              | 通道状态更新次数，必须单调递增                           |
| Local Commitment  | 本方可在异常时广播的最新退出交易                          |
| Remote Commitment | 对方持有的承诺交易版本，用于监控旧状态                       |
| Revocation 材料     | 旧 remote commitment 被广播时构造惩罚交易所需的材料       |
| CSV 延迟            | 强制关闭后给对方惩罚的时间窗口                           |
| Pending 事务        | 尚未收敛的 open、splicing、lock、unlock、close 等事务 |

客户端必须在每次承诺状态更新后持久化最新承诺交易、承诺高度、撤销材料、channel point 和 pending 事务。只保存余额不足以证明用户仍然控制资产。

## 资产模型

STP 不重新定义 BTC L1 资产协议，而是把它们纳入通道和聪网状态。

| 资产    | STP 处理原则                                               |
| ----- | ------------------------------------------------------ |
| 白聪    | BTC L1 受 dust 和 fee 约束；SatoshiNet L2 可以存在 0 聪 UTXO     |
| ORDX  | 必然绑定聪，进入聪网时按 `bindingSat` 计算承载关系；`ordx:o` 类型对象不 ascend |
| Runes | L2 不需要绑定聪，可以由 0 聪 enUTXO 携带；L1 输出仍遵守 BTC 规则            |
| BRC20 | L2 不需要绑定聪；L1 进入或退出可能需要 transfer inscription 和相关交易包     |

如果一个 L1 UTXO 同时携带多种可 ascend 资产，STP 只处理用户在操作中明确指定的一种资产。未指定资产不会进入聪网。客户端内部选币通常避开多资产 UTXO；如果必须使用，需要在用户授权前清楚提示哪些资产不会 ascend。

## 通道状态

通道状态可以抽象为：

| 状态                    | 含义                       |
| --------------------- | ------------------------ |
| `INIT`                | 通道协商开始                   |
| `FUNDING_BROADCASTED` | BTC L1 funding 交易已广播     |
| `FUNDING_CONFIRMED`   | funding 交易已确认            |
| `ANCHOR_BROADCASTED`  | 聪网 ascend / anchor 交易已广播 |
| `ANCHOR_CONFIRMED`    | ascend / anchor 已确认      |
| `READY`               | 通道可执行普通价值移动              |
| `CLOSING`             | 协商关闭中                    |
| `FORCE_CLOSING`       | 一方广播承诺交易强制关闭             |
| `SWEEPING`            | CSV 到期后清扫资产              |
| `CLOSED`              | 通道关闭完成                   |
| `PUNISHED`            | 旧状态被惩罚，通道终止              |

普通价值移动只能在 `READY` 状态发起。存在 pending 事务、承诺覆盖未知、链上状态不明或 indexer 未收敛时，客户端应停止新的 splicing、lock、unlock 或 close。

## 协议操作

### Open

Open 建立用户与 Core Node 的私人通道。普通用户不需要质押资产。流程包括通道参数协商、L1 funding、初始承诺交易签名、funding 确认、L2 ascend / anchor 和通道 ready。

客户端必须校验：

1. 通道地址由用户公钥和 Core Node 公钥生成。
2. funding 输出支付到正确通道地址。
3. 服务费、手续费和找零符合用户授权。
4. 初始承诺交易可被用户单方面广播。
5. Core Node 签名有效。
6. L1 funding 与 L2 ascend / anchor 可以通过 indexer 复核。

### Splicing-in / Expand

Splicing-in 将新的 BTC L1 资产纳入已有通道。它可能包含 L1 转入通道地址、L2 ascend / anchor、承诺状态更新和通道容量变化。

Expand 用于资产已经位于通道地址，但尚未纳入当前承诺状态的场景。典型情况包括：用户已经把资产转入通道地址、前序 splicing-in 被网络异常打断、或通道恢复时发现通道地址上存在尚未由当前承诺覆盖的资产。

客户端原则上不要求用户手动选择资产 UTXO 或 fee UTXO。钱包 adapter 应根据资产、金额、网络费和协议规则内部选择或构造合适输入。BRC20 如果没有合适 transfer UTXO，adapter 可以内部铸造 transfer inscription 再完成 splicing-in。

### Unlock

Unlock 将通道中属于用户的资产释放到聪网个人地址。释放后，资产由用户在 L2 上单签控制，可用于转账、合约或后续 lock。

Unlock 会推进承诺高度。客户端必须在操作前确认通道 ready、无 pending 事务、最新承诺交易存在、惩罚覆盖可证明，并在操作后复核 commit height 单调增加。

### Lock / Lock-with-expand

Lock 将聪网个人地址上的资产重新纳入通道保护。Lock 后，资产重新进入 RSMC 承诺安全边界。

Lock-with-expand 用于通道容量不足或当前通道资产集合不足以覆盖目标资产的场景。它应帮助用户把资产重新纳入通道控制权，是保障用户随时恢复资产控制的重要能力。

Lock 和 unlock 一样，原则上不要求用户提供输入 UTXO 或 fee UTXO。adapter 应内部选择 L2 资产输入，并返回可验证的事务证据。

### Splicing-out

Splicing-out 将通道资产退出到 BTC L1 地址。它通常包含通道承诺更新、L2 descend / de-anchor、L1 输出和后续 indexer 确认。

客户端必须校验：

1. 退出资产、金额和目标地址符合用户授权。
2. L2 descend 与 L1 输出可以被 indexer 关联。
3. L1 输出满足对应资产协议的转移规则。
4. 手续费输入来自合法来源；除白聪 unlock 的内部例外外，发起方 fee 不应使用通道地址 UTXO。

### Close / Force Close / Sweep

Close 是双方协商关闭通道。Force close 是一方广播最新承诺交易单方面关闭。Sweep 是 CSV 到期后清扫属于自己的延迟输出或通道地址上的可清扫资产。

当 Core Node 不可用时，客户端必须能给出 force close plan：可广播的 local commitment、CSV 延迟、后续 sweep 条件和预计风险。Agent 不应在缺少承诺交易或 sweep 路径时建议用户继续依赖该通道。

### Punish

如果 Core Node 广播旧 remote commitment，客户端应识别该 commitment 已被撤销，并使用对应撤销材料构造惩罚交易。惩罚交易的目标是让作恶方无法通过旧状态获利。

客户端应在每次承诺高度推进后更新 punish coverage，并向上层返回：

1. 是否存在已撤销 remote commitment。
2. 每个已撤销 remote commitment 是否有可验证、可广播的 punish tx 或构造材料。
3. 当前 CSV 窗口是否仍允许惩罚。
4. punish 广播后的通道终止状态。

主网客户端不得依赖测试网故障注入接口。测试网可以提供保留旧 commitment、广播旧 commitment 等接口，用于证明 Agent 确实能识别旧状态并广播 punish。

## 网络不确定性

STP 客户端必须区分“明确失败”和“结果未知”。Timeout、EOF、连接中断、服务重启或 indexer 暂未收敛，都不能直接被当作交易未发生。

推荐规则：

1. 进入广播或最终承诺交换前，先持久化 pending 事务、通道快照和相关交易 ID。
2. 广播调用结果未知时，先查询 L1/L2 交易是否可见。
3. 如果交易可见，继续轮询确认，不重复消费输入。
4. 如果交易暂不可见，也应锁定相关输入并保留 pending，等待监控流程收敛。
5. 只有双方仍处于同一旧安全状态、无 pending 事务、相关交易均不可见时，才允许重新发起同类操作。

这条规则适用于 open、splicing-in、splicing-out、unlock、lock、close 和 force close。

## 通道恢复

STP 客户端应支持以下恢复能力：

| 能力                  | 场景                                                        |
| ------------------- | --------------------------------------------------------- |
| Restore             | 本地进程或数据库异常，但可从本地备份、peer 或持久化状态恢复最新通道                      |
| Reopen              | 通道已关闭，但通道地址仍有属于用户的资产，需要恢复同一 client-core 通道身份              |
| Rebuild             | 通道状态丢失或 L1 channel point 变化，需要依赖 L1/L2 ledger 重新分配资产和承诺状态 |
| Expand              | 已在通道地址的资产未纳入当前承诺状态，需要纳入通道管理                               |
| Clean stale channel | 链上已经关闭或惩罚完成，本地仍残留旧 active channel，需要先清理再重新 open           |

恢复流程不得重复发行聪网资产。判断某个 L1 UTXO 是否需要 ascend，应优先依据 L2 channel ledger 中的 ascend / descend 记录，以及 L1/L2 indexer 对通道地址资产的当前视图。无法证明的资产不应自动 anchor。

## 客户端最低要求

一个安全 STP 客户端至少要具备：

1. 密钥管理和消息签名。
2. Core Node 发现和身份校验。
3. BTC L1 与 SatoshiNet 查询能力。
4. L1/L2 交易构造、签名、验证和广播能力。
5. 通道状态、承诺交易、撤销材料和 pending 事务持久化。
6. 资产协议解析和金额精度校验。
7. 结果未知恢复。
8. Safety snapshot、commitment export、punish status、force close plan 和 sweep build 等安全接口。

互操作文档见：

| 文档                                                                  | 用途                                                     |
| ------------------------------------------------------------------- | ------------------------------------------------------ |
| [STP 消息与数据模型](/xie-yi-yu-an-quan/stp/messages-and-data-model)       | 定义第三方客户端需要理解的消息族、公共字段、资产对象、承诺对象和错误语义                   |
| [STP 消息流程](/xie-yi-yu-an-quan/stp/message-sequences)                | 按 open、splicing、lock、unlock、close、punish 等操作说明消息顺序和验证点 |
| [第三方 STP 客户端接入指南](/xie-yi-yu-an-quan/stp/client-integration)        | 面向钱包、SDK、PWA adapter、CLI 和 AI Agent 的接入接口建议            |
| [STP 第三方客户端实现验收清单](/xie-yi-yu-an-quan/stp/implementation-checklist) | 第三方客户端进入测试网和主网前必须通过的能力检查                               |

## 面向 AI Agent 的可验证安全

STP 希望让 AI Agent 不只是“会调用接口”，而是能判断资产是否仍在用户控制下。Agent 在价值移动前至少应确认：

1. 通道处于 ready。
2. 本地持有最新 local commitment。
3. remote commitment 的旧状态均有 punish coverage。
4. commit height 单调增加，没有回退。
5. L1/L2 indexer 证据与钱包本地状态一致。
6. 不存在 pending 或结果未知的价值移动事务。
7. 用户私钥、助记词和签名始终留在钱包安全边界内。

如果这些条件不能成立，Agent 应停止普通操作，并进入恢复、强制关闭、惩罚或人工确认路径。


# STP 消息与数据模型

本文定义第三方 STP 客户端需要理解的协议消息、公共数据对象和错误语义。它面向钱包、SDK、PWA adapter、CLI、后端服务和 AI Agent 工具，目标是让任何开发语言都能实现客户端并接入兼容的 Core Node。

本文不是某个代码库的类型说明。开源 wallet SDK 中的 wire message 名称可以作为互操作参考，但协议实现应以本文描述的语义、签名、状态推进和可验证证据为准。

## SDK 源码参考

STP client / peer 消息定义已经迁移到开源 wallet SDK。本文给出协议层结构，源码是开发者核对字段名和最新 wire 定义的直接入口：

| 内容                            | GitHub                                                                                                                           |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| STP channel 消息                | [sat20wallet/sdk/wire/types\_stp\_channel.go](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wire/types_stp_channel.go) |
| Ping、ActionSync、PerformAction | [sat20wallet/sdk/wire/types.go](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wire/types.go)                           |
| `MsgHeader`、`BaseResp`        | [sat20wallet/sdk/wire/types\_contract.go](https://github.com/sat20-labs/sat20wallet/blob/main/sdk/wire/types_contract.go)        |

跨语言实现应以 JSON 字段名作为互操作边界。二进制字段在现有 Go SDK 中按 `[]byte` JSON 规则编码；非 Go 实现应在 adapter 层固定 hex 或 base64 编码，并在签名序列化中保持确定性。

## 参与方

| 参与方            | 协议职责                                                                         |
| -------------- | ---------------------------------------------------------------------------- |
| Client Wallet  | 用户钱包或受钱包授权的 adapter。持有用户私钥、通道状态、承诺交易、撤销材料和 pending 事务                        |
| Core Node      | 为普通用户提供 STP 服务的节点。它与 Client Wallet 建立私人通道，协签承诺交易，维护服务侧通道状态，并运行或配置 L1 indexer |
| Bootstrap Node | Core Node 的发现、准入和网络组织角色。普通用户打开私人通道时不直接把 Bootstrap Node 当作 STP peer           |
| L1 Indexer     | BTC L1 资产事实层。解析 UTXO、Ordinals、ORDX、BRC20、Runes、确认数、交易可见性和 reorg              |
| L2 Indexer     | SatoshiNet 资产事实层。解析聪网 UTXO、ascend、descend、通道、合约和交易确认                         |

普通 STP 消息主要发生在 Client Wallet 和 Core Node 之间。L1/L2 indexer 不签署通道状态，但它们提供客户端验证资产事实和恢复 pending 事务所需的证据。

## 协议分层

STP 客户端通常分三层实现：

| 层            | 内容                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------ |
| 用户操作层        | `stp.open`、`stp.splicing_in`、`stp.unlock`、`stp.lock`、`stp.close` 等 JSON 操作。它面向 UI、CLI 和 AI Agent |
| STP peer 消息层 | Client Wallet 与 Core Node 之间的认证消息。它负责协商、签名、撤销、ack 和状态推进                                          |
| 链与索引证据层      | BTC L1、SatoshiNet、L1 indexer、L2 indexer 返回的 UTXO、资产、交易、ascend、descend 和通道状态                      |

上层 adapter 可以隐藏资产 UTXO、fee UTXO、BRC20 transfer inscription、stub UTXO 和交易包细节，但不能隐藏安全证据。Agent 至少要能读取 safety snapshot、commitment export、punish status、force close plan 和 transaction status。

## 消息信封

所有会改变通道状态、消耗资产、泄露撤销材料或确认广播结果的消息，都必须可认证。推荐信封如下：

| 字段              | 含义                               |
| --------------- | -------------------------------- |
| `version`       | 协议消息版本                           |
| `msg_id`        | 消息类型或路径                          |
| `chain`         | 网络标识，例如 mainnet、testnet、testnet4 |
| `channel_id`    | 通道地址或通道标识                        |
| `commit_height` | 当前承诺高度；会改变承诺状态的消息必须携带            |
| `request_id`    | 本次事务的稳定 ID，用于重试和恢复               |
| `sender_pubkey` | 发送方公钥                            |
| `node_id`       | Core Node 身份，可选但建议携带             |
| `payload`       | 具体消息内容                           |
| `signature`     | 对除签名字段外的确定性序列化内容签名               |

接收方必须校验签名、链 ID、通道身份、发送方身份、承诺高度和资产数量。承诺高度回退、链 ID 不匹配、签名无效、资产不守恒或消息与 pending 事务不一致，都必须拒绝。

## 公共数据对象

### Channel Identity

| 字段                 | 含义                                    |
| ------------------ | ------------------------------------- |
| `channel_id`       | 通道标识，通常可由通道地址表示                       |
| `channel_address`  | Client Wallet 与 Core Node 的 2-of-2 地址 |
| `client_pubkey`    | 用户通道公钥                                |
| `core_node_pubkey` | Core Node 通道公钥                        |
| `channel_point`    | 当前承诺交易花费的 BTC L1 outpoint             |
| `commit_height`    | 当前承诺高度                                |
| `csv_delay`        | 强制关闭后的惩罚窗口                            |

### Asset Descriptor

| 字段                    | 含义                              |
| --------------------- | ------------------------------- |
| `asset_type`          | `sats`、`ordx`、`runes`、`brc20` 等 |
| `asset_name`          | 协议资产名                           |
| `amount`              | 资产数量，使用字符串避免精度问题                |
| `binding_sat`         | ORDX 等绑定聪资产的绑定参数                |
| `selected_asset_only` | 当一个 UTXO 有多种资产时，本次只处理用户明确指定的资产  |

### UTXO Reference

| 字段           | 含义                       |
| ------------ | ------------------------ |
| `outpoint`   | `txid:vout`              |
| `address`    | 所属地址                     |
| `value_sats` | 白聪数量；SatoshiNet L2 可以为 0 |
| `assets`     | 该输出携带的资产列表               |
| `spendable`  | 是否已经可作为下一笔交易输入           |
| `source`     | `l1` 或 `l2`              |

### Commitment Descriptor

| 字段                      | 含义                                |
| ----------------------- | --------------------------------- |
| `commitment_txid`       | 承诺交易 ID                           |
| `commitment_tx`         | 交易 hex 或结构化只读对象                   |
| `commit_height`         | 该承诺对应的高度                          |
| `owner`                 | `local` 或 `remote`                |
| `channel_point`         | 该承诺花费的通道 outpoint                 |
| `balances`              | 该承诺下双方资产归属                        |
| `deanchor_tx`           | 对应的 L2 descend / de-anchor 交易，可为空 |
| `prev_txs` / `next_txs` | 为 BRC20、stub 或交易包准备的关联交易          |
| `others`                | 用于清扫通道地址中用户资产的附加承诺或清扫交易           |

客户端不能只保存余额。每次承诺高度推进后，必须持久化最新 local commitment、remote commitment、撤销材料、关联交易和 pending 事务。

### Revocation Descriptor

| 字段                        | 含义                                                 |
| ------------------------- | -------------------------------------------------- |
| `revocation_hash`         | 旧状态撤销承诺                                            |
| `revocation_secret`       | 撤销秘密或其受控引用，不应暴露给未授权上层                              |
| `next_commitment_point`   | 下一承诺点                                              |
| `revoked_commitment_txid` | 已撤销 remote commitment                              |
| `punish_material_status`  | `missing`、`verified`、`broadcastable`、`broadcasted` |

### Safety Snapshot

| 字段                    | 含义                                                        |
| --------------------- | --------------------------------------------------------- |
| `status`              | `READY_SAFE`、`READY_DEGRADED`、`PUNISH_COVERAGE_UNKNOWN` 等 |
| `channel_id`          | 通道标识                                                      |
| `commit_height`       | 当前承诺高度                                                    |
| `channel_point`       | 当前通道 outpoint                                             |
| `local_commitment`    | 本方可广播的最新退出交易摘要                                            |
| `remote_commitments`  | 对方承诺状态摘要和撤销覆盖                                             |
| `punish_coverage`     | 旧 remote commitment 的惩罚覆盖                                 |
| `pending`             | 未完成事务                                                     |
| `l1_view` / `l2_view` | indexer 证据摘要                                              |

## 消息结构索引

本节列出第三方客户端需要实现或理解的主要消息结构。字段类型使用协议层表达：`bytes` 表示二进制数据，`bytes[]` 表示二进制数组，`bytes[][]` 表示二维签名数组，`string[]` 表示字符串数组。

为保持表格可读性，本文会把一组 embedded 字段写成 `CommitSigInfo`、`SplicingSigInfo` 或 `RevokeAndAck`。实际 JSON wire 中这些字段按 SDK 定义展开，第三方实现应以字段名和签名序列化规则保持兼容。

### 公共结构

`MsgHeader`

| 字段        | 类型     | 说明      |
| --------- | ------ | ------- |
| `version` | int    | 消息版本    |
| `msgId`   | string | 消息类型或路径 |

`BaseResp`

| 字段     | 类型     | 说明                |
| ------ | ------ | ----------------- |
| `code` | int    | `0` 表示成功，非 0 表示失败 |
| `msg`  | string | 错误或状态文本           |

`OpenChannelFee`

| 字段                  | 类型    | 说明                                             |
| ------------------- | ----- | ---------------------------------------------- |
| `manageFee`         | int64 | 通道管理费用                                         |
| `mortgageFee`       | int64 | Core Node 准入或特定服务相关费用；普通 client open 不应理解为用户质押 |
| `minReserveSats`    | int64 | 通道最低保留白聪                                       |
| `commitmentFee`     | int64 | 承诺交易费用预算                                       |
| `commitmentFeeRate` | int64 | 承诺交易费率参数                                       |
| `splicingInFee`     | int64 | splicing-in 服务费用                               |
| `splicingOutFee`    | int64 | splicing-out 服务费用                              |

`CommitSigInfo`

| 字段                     | 类型             | 说明                                                   |
| ---------------------- | -------------- | ---------------------------------------------------- |
| `commitSig`            | bytes\[]       | commitment 签名                                        |
| `commitDeAnchorSig`    | bytes\[]       | commitment 对应 de-anchor / anchor 签名                  |
| `commitPrevTxSig`      | bytes\[]\[]    | commitment 前置交易签名，例如 BRC20 transfer inscription 相关交易 |
| `commitNextTxSig`      | bytes\[]\[]    | commitment 后续交易签名                                    |
| `commitOtherPrevTxSig` | bytes\[]\[]\[] | 附加清扫交易的前置交易签名                                        |
| `commitOtherTxSig`     | bytes\[]\[]    | 附加清扫交易签名                                             |

`SplicingSigInfo`

| 字段                  | 类型          | 说明                      |
| ------------------- | ----------- | ----------------------- |
| `splicingPrevTxSig` | bytes\[]\[] | splicing 前置交易签名         |
| `splicingSig`       | bytes\[]    | splicing 交易签名           |
| `deAnchorSig`       | bytes\[]    | de-anchor 或 anchor 交易签名 |

`RevokeAndAck`

| 字段           | 类型      | 说明                                        |
| ------------ | ------- | ----------------------------------------- |
| `revocation` | bytes32 | 上一个 commitment revocation hash 的 preimage |
| `nextRevKey` | bytes   | 下一承诺点或下一 revocation key                   |

### 连接与同步结构

`AbbrChannelInfo`

| 字段                      | 类型     | 说明          |
| ----------------------- | ------ | ----------- |
| `version`               | int    | 通道数据版本      |
| `channelId`             | string | 通道标识        |
| `commitHeight`          | int    | 当前承诺高度      |
| `staticMerkleRoot`      | bytes  | 静态通道数据 root |
| `localAssetMerkleRoot`  | bytes  | 本方资产 root   |
| `remoteAssetMerkleRoot` | bytes  | 对方资产 root   |

`PingRequest`

| 字段                  | 类型              | 说明              |
| ------------------- | --------------- | --------------- |
| `version` / `msgId` | MsgHeader       | 消息头             |
| `pubKey`            | bytes           | 发送方公钥           |
| `mode`              | string          | ping 模式         |
| `info`              | AbbrChannelInfo | 通道摘要，可为空        |
| `nodeId`            | bytes           | Core Node 身份，可选 |

`PingReq = PingRequest + msgSig`

| 字段       | 类型    | 说明       |
| -------- | ----- | -------- |
| `msgSig` | bytes | 对消息内容的签名 |

`PingResp`

| 字段             | 类型       | 说明           |
| -------------- | -------- | ------------ |
| `code` / `msg` | BaseResp | 结果           |
| `commitHeight` | int      | peer 看到的承诺高度 |
| `action`       | string   | 下一动作         |
| `param`        | string   | 下一动作参数       |
| `paramSig`     | bytes    | 参数签名         |

`ActionSyncReq = ActionSyncRequest + msgSig`

| 字段                  | 类型        | 说明              |
| ------------------- | --------- | --------------- |
| `version` / `msgId` | MsgHeader | 消息头             |
| `pubKey`            | bytes     | 请求方公钥           |
| `reason`            | string    | 同步原因            |
| `nodeId`            | bytes     | Core Node 身份，可选 |
| `msgSig`            | bytes     | 请求签名            |

`ActionSyncResp`

| 字段             | 类型       | 说明       |
| -------------- | -------- | -------- |
| `code` / `msg` | BaseResp | 结果       |
| `channelData`  | bytes    | 可恢复的通道数据 |

### Open 结构

`ChannelOpenReq = OpenChannelRequest + msgSig`

| 字段                    | 类型        | 说明                      |
| --------------------- | --------- | ----------------------- |
| `version` / `msgId`   | MsgHeader | 消息头                     |
| `nodeId`              | bytes     | Core Node 身份            |
| `channelType`         | int       | 通道类型                    |
| `channelWalletId`     | int       | 子钱包或子账户 ID              |
| `fundingKey`          | bytes     | 本方 funding 公钥           |
| `feeRate`             | int64     | BTC L1 费率参数             |
| `localFundingAmount`  | int64     | 本方 funding 白聪数量         |
| `outpoints`           | string\[] | 可选 funding 输入           |
| `needSendFundingTx`   | bool      | 是否需要客户端构造并广播 funding tx |
| `skipOpeningAnchorTx` | bool      | 恢复场景是否跳过 opening anchor |
| `l2DrainTxId`         | string    | 恢复场景关联的 L2 drain txid   |
| `memo`                | bytes     | 备注                      |
| `msgSig`              | bytes     | 请求签名                    |

`ChannelOpenResp = BaseResp + AcceptChannel`

| 字段             | 类型             | 说明                              |
| -------------- | -------------- | ------------------------------- |
| `id`           | int64          | 本次 open reservation ID          |
| `commitHeight` | int            | 初始承诺高度                          |
| `csv`          | uint16         | CSV 延迟                          |
| `openFee`      | OpenChannelFee | open 费用参数                       |
| `fundingKey`   | bytes          | Core Node funding 公钥            |
| `revbasePoint` | bytes          | Core Node revocation base point |
| `commitPoint`  | bytes          | Core Node commitment point      |
| `invoiceSig`   | bytes          | 服务端 invoice 签名                  |

`FundingCreatedReq = FundingCreated + msgSig`

| 字段             | 类型       | 说明                        |
| -------------- | -------- | ------------------------- |
| `id`           | int64    | open reservation ID       |
| `fundingPoint` | string   | funding outpoint          |
| `revbasePoint` | bytes    | 客户端 revocation base point |
| `commitPoint`  | bytes    | 客户端 commitment point      |
| `commitSig`    | bytes\[] | 客户端初始 commitment 签名       |
| `deAnchorSig`  | bytes\[] | 客户端 de-anchor 签名          |
| `msgSig`       | bytes    | 请求签名                      |

`FundingCreatedResp = BaseResp + FundingSigned`

| 字段            | 类型       | 说明                      |
| ------------- | -------- | ----------------------- |
| `id`          | int64    | open reservation ID     |
| `commitSig`   | bytes\[] | Core Node commitment 签名 |
| `deAnchorSig` | bytes\[] | Core Node de-anchor 签名  |

`FundingBroadcastedReq = FundingBroadcasted + msgSig`

| 字段            | 类型     | 说明                       |
| ------------- | ------ | ------------------------ |
| `id`          | int64  | open reservation ID      |
| `fundingTxId` | string | 已广播的 BTC L1 funding txid |
| `msgSig`      | bytes  | 请求签名                     |

`FundingBroadcastedResp = BaseResp`

### Unlock 结构

`UnlockReq = UnlockRequest + msgSig`

| 字段                  | 类型        | 说明                                           |
| ------------------- | --------- | -------------------------------------------- |
| `version` / `msgId` | MsgHeader | 消息头                                          |
| `channel`           | string    | 通道标识                                         |
| `commitHeight`      | int       | 当前承诺高度                                       |
| `assetName`         | string    | 资产名                                          |
| `amt`               | string\[] | 释放数量列表                                       |
| `feeRate`           | int64     | 兼容字段；SatoshiNet unlock 不应要求用户设置 BTC fee rate |
| `feeUtxos`          | string\[] | 兼容字段；adapter 不应暴露给普通 Agent 选择                |
| `address`           | string\[] | 目标 L2 地址列表                                   |
| `memo`              | bytes     | 备注                                           |
| `reason`            | string    | 操作原因                                         |
| `more`              | bytes     | 扩展数据                                         |
| `nodeId`            | bytes     | Core Node 身份，可选                              |
| `msgSig`            | bytes     | 请求签名                                         |

`UnlockResp`

| 字段             | 类型       | 说明                |
| -------------- | -------- | ----------------- |
| `code` / `msg` | BaseResp | 结果                |
| `id`           | int64    | reservation ID    |
| `revealKey`    | bytes    | 本轮 reveal key     |
| `rev`          | bytes    | 本轮 revocation key |
| `nextRevKey`   | bytes    | 下一 revocation key |
| `feeRate`      | int64    | 返回的费用参数           |

`UnlockCommitSigReq = CommitSigInfo + rev keys + msgSig`

| 字段              | 类型            | 说明                  |
| --------------- | ------------- | ------------------- |
| `channel`       | string        | 通道标识                |
| `id`            | int64         | reservation ID      |
| `commitSigInfo` | CommitSigInfo | 新 commitment 相关签名集合 |
| `rev`           | bytes         | 本方 revocation key   |
| `nextRevKey`    | bytes         | 本方下一 revocation key |
| `msgSig`        | bytes         | 请求签名                |

`UnlockCommitSigResp = BaseResp + CommitSigInfo + RevokeAndAck`

| 字段              | 类型            | 说明                   |
| --------------- | ------------- | -------------------- |
| `id`            | int64         | reservation ID       |
| `commitSigInfo` | CommitSigInfo | 对方 commitment 相关签名集合 |
| `rev`           | RevokeAndAck  | 对方对旧状态的撤销确认          |

`UnlockRevokeAndAckReq`

| 字段          | 类型           | 说明             |
| ----------- | ------------ | -------------- |
| `channel`   | string       | 通道标识           |
| `id`        | int64        | reservation ID |
| `rev`       | RevokeAndAck | 客户端对旧状态的撤销确认   |
| `unlockSig` | bytes\[]     | unlock 交易签名    |
| `msgSig`    | bytes        | 请求签名           |

`UnlockRevokeAndAckResp`

| 字段             | 类型       | 说明                    |
| -------------- | -------- | --------------------- |
| `code` / `msg` | BaseResp | 结果                    |
| `id`           | int64    | reservation ID        |
| `unlockSig`    | bytes\[] | Core Node unlock 交易签名 |

### Lock 结构

`LockReq = LockRequest + msgSig`

| 字段                  | 类型        | 说明                  |
| ------------------- | --------- | ------------------- |
| `version` / `msgId` | MsgHeader | 消息头                 |
| `channel`           | string    | 通道标识                |
| `commitHeight`      | int       | 当前承诺高度              |
| `assetName`         | string    | 资产名                 |
| `amt`               | string    | 锁入数量                |
| `feeRate`           | int64     | 兼容字段                |
| `lockUtxos`         | string\[] | 兼容字段；adapter 通常内部选择 |
| `feeUtxos`          | string\[] | 兼容字段；adapter 通常内部选择 |
| `revealKey`         | bytes     | reveal key          |
| `rev`               | bytes     | revocation key      |
| `nextRevKey`        | bytes     | 下一 revocation key   |
| `needSendLockTx`    | bool      | 是否需要发送 lock tx      |
| `memo`              | bytes     | 备注                  |
| `reason`            | string    | 操作原因                |
| `more`              | bytes     | 扩展数据                |
| `nodeId`            | bytes     | Core Node 身份，可选     |
| `msgSig`            | bytes     | 请求签名                |

`LockResp = BaseResp + CommitSigInfo + rev keys`

| 字段              | 类型            | 说明                          |
| --------------- | ------------- | --------------------------- |
| `id`            | int64         | reservation ID              |
| `feeRate`       | int64         | 返回的费用参数                     |
| `commitSigInfo` | CommitSigInfo | Core Node commitment 相关签名   |
| `rev`           | bytes         | Core Node revocation key    |
| `nextRevKey`    | bytes         | Core Node 下一 revocation key |

`LockCommitSigAndRevokeReq`

| 字段              | 类型            | 说明                  |
| --------------- | ------------- | ------------------- |
| `channel`       | string        | 通道标识                |
| `id`            | int64         | reservation ID      |
| `commitSigInfo` | CommitSigInfo | 客户端 commitment 相关签名 |
| `rev`           | RevokeAndAck  | 客户端对旧状态的撤销确认        |
| `msgSig`        | bytes         | 请求签名                |

`LockCommitSigAndRevokeResp`

| 字段             | 类型           | 说明                  |
| -------------- | ------------ | ------------------- |
| `code` / `msg` | BaseResp     | 结果                  |
| `id`           | int64        | reservation ID      |
| `rev`          | RevokeAndAck | Core Node 对旧状态的撤销确认 |
| `lockSig`      | bytes\[]     | Core Node lock 交易签名 |

`LockAckReq`

| 字段        | 类型       | 说明             |
| --------- | -------- | -------------- |
| `channel` | string   | 通道标识           |
| `id`      | int64    | reservation ID |
| `lockSig` | bytes\[] | 客户端 lock 交易签名  |
| `msgSig`  | bytes    | 请求签名           |

`LockAckResp = BaseResp + id`

### Splicing-in 结构

`SplicingInReq = SplicingInRequest + msgSig`

| 字段                   | 类型        | 说明                           |
| -------------------- | --------- | ---------------------------- |
| `version` / `msgId`  | MsgHeader | 消息头                          |
| `channel`            | string    | 通道标识                         |
| `commitHeight`       | int       | 当前承诺高度                       |
| `assetName`          | string    | 资产名                          |
| `amt`                | string    | 加入通道的资产数量                    |
| `stub`               | string    | stub UTXO，可选                 |
| `utxos`              | string\[] | 兼容字段；adapter 通常内部选择资产 UTXO   |
| `fees`               | string\[] | 兼容字段；adapter 通常内部选择 fee UTXO |
| `preTxInputs`        | string\[] | 前置交易输入                       |
| `revealKey`          | bytes     | reveal key                   |
| `needSendSplicingTx` | bool      | 是否需要构造并广播 L1 splicing tx     |
| `feeRate`            | int64     | BTC L1 费率参数                  |
| `reason`             | string    | 操作原因                         |
| `memo`               | bytes     | 备注                           |
| `nodeId`             | bytes     | Core Node 身份，可选              |
| `msgSig`             | bytes     | 请求签名                         |

`SplicingInResp`

| 字段                 | 类型       | 说明                          |
| ------------------ | -------- | --------------------------- |
| `code` / `msg`     | BaseResp | 结果                          |
| `id`               | int64    | reservation ID              |
| `serviceFee`       | int64    | 服务费                         |
| `rev`              | bytes    | Core Node revocation key    |
| `nextRevKey`       | bytes    | Core Node 下一 revocation key |
| `newCapacity`      | int64    | 新通道容量                       |
| `newLocalBalance`  | string   | 新本方余额                       |
| `newRemoteBalance` | string   | 新对方余额                       |
| `invoiceSig`       | bytes    | invoice 签名                  |

`SplicingInCommitSigReq = SplicingSigInfo + CommitSigInfo + rev keys + msgSig`

| 字段                | 类型              | 说明                             |
| ----------------- | --------------- | ------------------------------ |
| `channel`         | string          | 通道标识                           |
| `id`              | int64           | reservation ID                 |
| `splicingSigInfo` | SplicingSigInfo | splicing 与 anchor/de-anchor 签名 |
| `commitSigInfo`   | CommitSigInfo   | commitment 签名                  |
| `rev`             | bytes           | 客户端 revocation key             |
| `nextRevKey`      | bytes           | 客户端下一 revocation key           |
| `msgSig`          | bytes           | 请求签名                           |

`SplicingInCommitSigResp = BaseResp + SplicingSigInfo + CommitSigInfo + RevokeAndAck`

`SplicingInRevokeAndAckReq`

| 字段        | 类型           | 说明             |
| --------- | ------------ | -------------- |
| `channel` | string       | 通道标识           |
| `id`      | int64        | reservation ID |
| `txId`    | string       | splicing txid  |
| `rev`     | RevokeAndAck | 客户端对旧状态的撤销确认   |
| `msgSig`  | bytes        | 请求签名           |

`SplicingInRevokeAndAckResp = BaseResp + id`

### Splicing-out 结构

`SplicingOutReq = SplicingOutRequest + msgSig`

| 字段                  | 类型        | 说明                           |
| ------------------- | --------- | ---------------------------- |
| `version` / `msgId` | MsgHeader | 消息头                          |
| `channel`           | string    | 通道标识                         |
| `commitHeight`      | int       | 当前承诺高度                       |
| `assetName`         | string    | 资产名                          |
| `amt`               | string    | 退出数量                         |
| `stub`              | string    | stub UTXO                    |
| `utxos`             | string\[] | 兼容字段；adapter 通常内部选择资产 UTXO   |
| `fees`              | string\[] | 兼容字段；adapter 通常内部选择 fee UTXO |
| `preTxInputs`       | string\[] | 前置交易输入                       |
| `revealKey`         | bytes     | reveal key                   |
| `address`           | string    | BTC L1 目标地址                  |
| `feeRate`           | int64     | BTC L1 费率参数                  |
| `reason`            | string    | 操作原因                         |
| `memo`              | bytes     | 备注                           |
| `nodeId`            | bytes     | Core Node 身份，可选              |
| `msgSig`            | bytes     | 请求签名                         |

`SplicingOutResp` 与 `SplicingInResp` 字段一致。

`SplicingOutCommitSigReq = SplicingSigInfo + CommitSigInfo + rev keys + msgSig`

`SplicingOutCommitSigResp = BaseResp + SplicingSigInfo + CommitSigInfo + RevokeAndAck`

`SplicingOutRevokeAndAckReq`

| 字段             | 类型           | 说明                          |
| -------------- | ------------ | --------------------------- |
| `channel`      | string       | 通道标识                        |
| `id`           | int64        | reservation ID              |
| `deAnchorTxId` | string       | L2 descend / de-anchor txid |
| `rev`          | RevokeAndAck | 客户端对旧状态的撤销确认                |
| `msgSig`       | bytes        | 请求签名                        |

`SplicingOutRevokeAndAckResp = BaseResp + id`

### Close 结构

`ChannelCloseReq = CloseChannelRequest + msgSig`

| 字段                  | 类型        | 说明              |
| ------------------- | --------- | --------------- |
| `version` / `msgId` | MsgHeader | 消息头             |
| `channel`           | string    | 通道标识            |
| `commitHeight`      | int       | 当前承诺高度          |
| `feeRate`           | int64     | BTC L1 费率参数，可选  |
| `revealKey`         | bytes     | reveal key，可选   |
| `nodeId`            | bytes     | Core Node 身份，可选 |
| `msgSig`            | bytes     | 请求签名            |

`ChannelCloseResp = BaseResp + ClosingSigned`

| 字段            | 类型          | 说明             |
| ------------- | ----------- | -------------- |
| `id`          | int64       | reservation ID |
| `deAnchorSig` | bytes\[]    | de-anchor 签名   |
| `closingsig`  | bytes\[]    | closing 交易签名   |
| `prevTxSig`   | bytes\[]\[] | 前置交易签名         |

`ClosingSignedReq`

| 字段            | 类型          | 说明               |
| ------------- | ----------- | ---------------- |
| `id`          | int64       | reservation ID   |
| `deAnchorSig` | bytes\[]    | 客户端 de-anchor 签名 |
| `closingsig`  | bytes\[]    | 客户端 closing 签名   |
| `prevTxSig`   | bytes\[]\[] | 客户端前置交易签名        |
| `channel`     | string      | 通道标识             |
| `msgSig`      | bytes       | 请求签名             |

`ClosingSignedResp`

| 字段             | 类型       | 说明                        |
| -------------- | -------- | ------------------------- |
| `code` / `msg` | BaseResp | 结果                        |
| `splicingTxId` | string   | 关闭过程中生成的退出或 splicing txid |

`ClosingBroadcastedReq`

| 字段             | 类型     | 说明                  |
| -------------- | ------ | ------------------- |
| `id`           | int64  | reservation ID      |
| `deAnchorTxId` | string | 已广播的 de-anchor txid |
| `channel`      | string | 通道标识                |
| `msgSig`       | bytes  | 请求签名                |

`ClosingBroadcastedResp = BaseResp`

### Recover Payment 结构

`RecoverPaymentRequireReq = RecoverPaymentRequest + msgSig`

| 字段                  | 类型        | 说明                 |
| ------------------- | --------- | ------------------ |
| `version` / `msgId` | MsgHeader | 消息头                |
| `channel`           | string    | 通道标识               |
| `commitHeight`      | int       | 当前承诺高度             |
| `paymentTxId`       | string    | 需要恢复的 payment txid |
| `reason`            | string    | 恢复原因               |
| `nodeId`            | bytes     | Core Node 身份，可选    |
| `msgSig`            | bytes     | 请求签名               |

Recover payment 后续结构与 unlock 的 commit-sig、revoke-and-ack 模式一致，只是最终签名字段为 `paymentSig`。

### PerformAction 结构

`PerformActionReq = PerformActionRequest + msgSig`

| 字段                  | 类型        | 说明                      |
| ------------------- | --------- | ----------------------- |
| `version` / `msgId` | MsgHeader | 消息头                     |
| `action`            | string    | action / reservation 类型 |
| `param`             | bytes     | action 参数               |
| `feeRate`           | int64     | BTC L1 费率参数             |
| `reqTime`           | int64     | 请求时间                    |
| `sendInL1`          | bool      | fee 或相关交易是否在 L1 发送      |
| `more`              | bytes     | 扩展数据                    |
| `pubKey`            | bytes     | 请求方公钥                   |
| `nodeId`            | bytes     | Core Node 身份，可选         |
| `msgSig`            | bytes     | 请求签名                    |

`PerformActionResp`

| 字段               | 类型       | 说明         |
| ---------------- | -------- | ---------- |
| `code` / `msg`   | BaseResp | 结果         |
| `id`             | int64    | action ID  |
| `serviceAddress` | string   | 服务费收款地址    |
| `serviceFee`     | int64    | 服务费        |
| `invoice`        | bytes    | invoice    |
| `invoiceSig`     | bytes    | invoice 签名 |

`PerformActionAckReq`

| 字段     | 类型     | 说明         |
| ------ | ------ | ---------- |
| `id`   | int64  | action ID  |
| `tx`   | string | fee 交易 hex |
| `txId` | string | fee txid   |

`PerformActionAckResp`

| 字段             | 类型       | 说明                |
| -------------- | -------- | ----------------- |
| `code` / `msg` | BaseResp | 结果                |
| `id`           | int64    | action ID         |
| `status`       | int      | action 状态         |
| `actionResvId` | int64    | 关联 reservation ID |
| `actionStatus` | int      | 关联 reservation 状态 |
| `actionResult` | bytes    | action 结果         |

## 消息族

### 连接与同步

| 消息                                    | 方向                         | 语义                          |
| ------------------------------------- | -------------------------- | --------------------------- |
| `PingRequest` / `PingReq`             | Client Wallet -> Core Node | 握手、身份证明、通道摘要同步              |
| `PingResponse` / `PingResp`           | Core Node -> Client Wallet | 返回 peer 当前承诺高度、下一动作或需要同步的信息 |
| `ActionSyncRequest` / `ActionSyncReq` | 任一方 -> 对方                  | 在重启、结果未知或状态不一致时请求同步事务状态     |
| `ActionSyncResp`                      | 对方 -> 请求方                  | 返回可同步的通道数据或 pending 事务数据    |

### Open Channel

| 消息                                      | 方向                         | 语义                                                                      |
| --------------------------------------- | -------------------------- | ----------------------------------------------------------------------- |
| `OpenChannelRequest` / `ChannelOpenReq` | Client Wallet -> Core Node | 请求打开私人通道，携带 funding 意图、通道公钥、金额和 memo                                    |
| `ChannelOpenResp`                       | Core Node -> Client Wallet | 接受通道，返回 CSV、费用、服务端 funding key、revocation base point 和 commitment point |
| `FundingCreatedReq`                     | Client Wallet -> Core Node | 提交 funding outpoint、初始承诺签名和相关 de-anchor 签名                              |
| `FundingCreatedResp`                    | Core Node -> Client Wallet | 返回服务端签名，形成双方可验证的初始承诺状态                                                  |
| `FundingBroadcastedReq`                 | Client Wallet -> Core Node | 通知 BTC L1 funding 已广播                                                   |
| `FundingBroadcastedResp`                | Core Node -> Client Wallet | 确认进入等待确认和 anchor 阶段                                                     |

Open 完成后，客户端必须能通过 L1 indexer 验证 funding，通过 L2 indexer 验证 ascend / anchor，并生成安全快照。

### Unlock

| 消息                            | 方向                         | 语义                                        |
| ----------------------------- | -------------------------- | ----------------------------------------- |
| `UnlockRequest` / `UnlockReq` | Client Wallet -> Core Node | 请求把通道资产释放到用户 L2 地址                        |
| `UnlockResp`                  | Core Node -> Client Wallet | 接受更新，返回本轮 revocation / next revocation 材料 |
| `UnlockCommitSigReq`          | Client Wallet -> Core Node | 发送新承诺签名，并提供本方下一状态材料                       |
| `UnlockCommitSigResp`         | Core Node -> Client Wallet | 返回服务端承诺签名和对旧状态的 revoke-and-ack            |
| `UnlockRevokeAndAckReq`       | Client Wallet -> Core Node | 客户端撤销旧状态并确认 unlock 交易签名                   |
| `UnlockRevokeAndAckResp`      | Core Node -> Client Wallet | 服务端确认，本轮状态推进完成                            |

Unlock 会推进 commit height。SatoshiNet 没有 BTC L1 fee rate 语义，普通 adapter 不应要求用户提供 fee UTXO。

### Lock

| 消息                           | 方向                         | 语义                             |
| ---------------------------- | -------------------------- | ------------------------------ |
| `LockRequest` / `LockReq`    | Client Wallet -> Core Node | 请求把用户 L2 资产重新锁回通道              |
| `LockResp`                   | Core Node -> Client Wallet | 接受更新，返回承诺签名材料和下一 revocation 材料 |
| `LockCommitSigAndRevokeReq`  | Client Wallet -> Core Node | 发送承诺签名并撤销旧状态                   |
| `LockCommitSigAndRevokeResp` | Core Node -> Client Wallet | 返回服务端撤销确认和 lock 交易签名           |
| `LockAckReq`                 | Client Wallet -> Core Node | 最终确认 lock 交易签名                 |
| `LockAckResp`                | Core Node -> Client Wallet | 本轮状态推进完成                       |

Lock-with-expand 可以理解为 Lock 与 Expand 的组合能力：当通道容量或资产集合不足时，客户端应能把资产重新纳入通道控制权。

### Splicing-in

| 消息                                    | 方向                         | 语义                                           |
| ------------------------------------- | -------------------------- | -------------------------------------------- |
| `SplicingInRequest` / `SplicingInReq` | Client Wallet -> Core Node | 请求把 BTC L1 资产加入已有通道                          |
| `SplicingInResp`                      | Core Node -> Client Wallet | 返回服务费、新容量、新余额和下一 revocation 材料               |
| `SplicingInCommitSigReq`              | Client Wallet -> Core Node | 发送 splicing、anchor/de-anchor、commitment 相关签名 |
| `SplicingInCommitSigResp`             | Core Node -> Client Wallet | 返回服务端对应签名和 revoke-and-ack                    |
| `SplicingInRevokeAndAckReq`           | Client Wallet -> Core Node | 通知 splicing 交易 ID 并撤销旧状态                     |
| `SplicingInRevokeAndAckResp`          | Core Node -> Client Wallet | 本轮状态推进完成                                     |

Expand 复用 splicing-in 的安全语义，但资产已经在通道地址上。客户端必须通过 L1/L2 indexer 判断是否已经 ascend，避免重复发行 L2 资产。

### Splicing-out

| 消息                                      | 方向                         | 语义                                                |
| --------------------------------------- | -------------------------- | ------------------------------------------------- |
| `SplicingOutRequest` / `SplicingOutReq` | Client Wallet -> Core Node | 请求把通道资产退出到 BTC L1 地址                              |
| `SplicingOutResp`                       | Core Node -> Client Wallet | 返回服务费、新容量、新余额和下一 revocation 材料                    |
| `SplicingOutCommitSigReq`               | Client Wallet -> Core Node | 发送 L1 退出、L2 descend / de-anchor 和 commitment 相关签名 |
| `SplicingOutCommitSigResp`              | Core Node -> Client Wallet | 返回服务端对应签名和 revoke-and-ack                         |
| `SplicingOutRevokeAndAckReq`            | Client Wallet -> Core Node | 通知 de-anchor 交易 ID 并撤销旧状态                         |
| `SplicingOutRevokeAndAckResp`           | Core Node -> Client Wallet | 本轮状态推进完成                                          |

Splicing-out 后，客户端必须能把 L2 descend 与 L1 输出通过 indexer 关联起来。BRC20 可能需要 transfer inscription 交易包，Runes 和 ORDX 必须遵守各自 L1 转移规则。

### Close

| 消息                                        | 方向                         | 语义                           |
| ----------------------------------------- | -------------------------- | ---------------------------- |
| `CloseChannelRequest` / `ChannelCloseReq` | Client Wallet -> Core Node | 请求协商关闭通道                     |
| `ChannelCloseResp`                        | Core Node -> Client Wallet | 返回 closing、de-anchor 和相关交易签名 |
| `ClosingSignedReq`                        | Client Wallet -> Core Node | 客户端签署关闭交易并提交                 |
| `ClosingSignedResp`                       | Core Node -> Client Wallet | 返回退出交易或 splicing 交易 ID       |
| `ClosingBroadcastedReq`                   | Client Wallet -> Core Node | 通知关闭相关交易已广播                  |
| `ClosingBroadcastedResp`                  | Core Node -> Client Wallet | 通道进入关闭完成或等待确认状态              |

Force close 不依赖对方在线。客户端广播最新 local commitment 后，必须按 CSV 条件构造 sweep，并继续监控 peer 是否广播旧状态。

### Recover Payment

| 消息                                                   | 方向        | 语义                                      |
| ---------------------------------------------------- | --------- | --------------------------------------- |
| `RecoverPaymentRequest` / `RecoverPaymentRequireReq` | 任一方 -> 对方 | 结果未知或 payment 状态不一致时请求恢复                |
| `RecoverPaymentRequireResp`                          | 对方 -> 请求方 | 返回恢复所需的 revocation / next revocation 材料 |
| `RecoverPaymentCommitSigReq`                         | 请求方 -> 对方 | 重新提交承诺签名                                |
| `RecoverPaymentCommitSigResp`                        | 对方 -> 请求方 | 返回对应承诺签名和 revoke-and-ack                |
| `RecoverPaymentRevokeAndAckReq`                      | 请求方 -> 对方 | 完成旧状态撤销与 payment 签名确认                   |
| `RecoverPaymentRevokeAndAckResp`                     | 对方 -> 请求方 | 恢复事务完成                                  |

### 远程动作

| 消息                                          | 方向                         | 语义                             |
| ------------------------------------------- | -------------------------- | ------------------------------ |
| `PerformActionRequest` / `PerformActionReq` | Client Wallet -> Core Node | 请求 Core Node 执行需要服务端参与的动作      |
| `PerformActionResp`                         | Core Node -> Client Wallet | 返回 action id、服务地址、服务费和 invoice |
| `PerformActionAckReq`                       | Client Wallet -> Core Node | 提交 fee 交易或确认材料                 |
| `PerformActionAckResp`                      | Core Node -> Client Wallet | 返回 action 状态和结果                |

远程动作不替代 STP 通道安全规则。只要动作会改变通道资产或承诺状态，就必须回到承诺交易、撤销材料、commit height 和 indexer 证据。

## 错误与结果未知

| 情况                            | 处理原则                                |
| ----------------------------- | ----------------------------------- |
| 签名无效、链 ID 错误、commit height 回退 | 明确失败，拒绝消息                           |
| 资产不守恒、UTXO 已花费、通道状态不匹配        | 明确失败或进入恢复；不得继续普通价值移动                |
| EOF、timeout、连接中断、服务重启         | 结果未知，不能直接当成失败                       |
| 交易广播后响应丢失                     | 按“可能成功”处理，查询 L1/L2 tx 可见性并锁定相关输入    |
| indexer 暂未返回交易                | 查询 mempool、peer 状态和 pending 事务，等待收敛 |

只有在双方仍处于同一旧安全状态、无 pending 事务、相关 L1/L2 交易均不可见时，客户端才可以重新做 preflight 并重试同类操作。

## 测试网故障注入

测试网可以开放保留旧 commitment、广播旧 commitment、构造 punish、广播 punish 等能力，让 AI Agent 验证自己确实持有保护用户资产的材料。

这些能力必须满足：

1. 只能在测试网启用。
2. 主网接口直接拒绝。
3. Agent 必须先 dry-run 验证 commitment、de-anchor、punish 和 sweep。
4. 广播旧 commitment 后，通道应立即进入关闭或已惩罚路径，不再允许普通价值移动。

主网安全不依赖故障注入接口。主网客户端依赖的是本地持久化承诺交易、撤销材料、watchtower 监控和 L1/L2 indexer 证据。


# STP 消息流程

本文按操作说明 STP 消息顺序、链上结果、状态推进和 Agent 验证点。它补充 [STP 消息与数据模型](/xie-yi-yu-an-quan/stp/messages-and-data-model)，用于第三方客户端实现、测试网演练和 AI Agent 自动化验证。

## 通用流程规则

每个会改变资产归属的 STP 操作都遵守以下规则：

1. 操作前读取 safety snapshot，确认通道处于可操作状态。
2. 客户端内部选择或构造输入，普通 Agent 不直接提供资产 UTXO 或 fee UTXO。
3. 双方先构造新承诺状态，再撤销旧承诺状态。
4. 进入广播或最终 ack 前，客户端必须持久化 pending 事务、相关 txid、承诺交易和撤销材料。
5. commit height 只能单调增加。
6. 广播后的网络异常视为结果未知，必须通过 L1/L2 indexer 和 peer 状态恢复。
7. 操作后重新读取 safety snapshot，确认 punish coverage 和资产事实。

## Open Channel

目标：建立 Client Wallet 与 Core Node 的私人 STP 通道。

| 步骤 | 消息 / 动作                                            | 验证点                                                   |
| -- | -------------------------------------------------- | ----------------------------------------------------- |
| 1  | Client Wallet 发现 Core Node                         | 校验网络、Core Node 公钥、能力列表、CSV、费用                         |
| 2  | `ChannelOpenReq`                                   | 请求打开普通 client-core 私人通道，普通用户不需要质押资产                   |
| 3  | `ChannelOpenResp`                                  | 校验 Core Node 签名、通道参数和初始 revocation / commitment point |
| 4  | 构造 BTC L1 funding                                  | funding 输出必须支付到 2-of-2 通道地址                           |
| 5  | `FundingCreatedReq` / `FundingCreatedResp`         | 双方交换初始承诺交易、de-anchor 和相关签名                            |
| 6  | 广播 funding                                         | 结果未知时锁定输入并轮询 L1                                       |
| 7  | `FundingBroadcastedReq` / `FundingBroadcastedResp` | 双方进入等待确认和 anchor 阶段                                   |
| 8  | L1 funding 确认，L2 ascend / anchor 确认                | L1/L2 indexer 都可复核                                    |
| 9  | 通道 ready                                           | safety snapshot 返回最新承诺交易和 punish coverage             |

Agent 验证：通道地址由 client pubkey 与 core node pubkey 生成；funding outpoint、初始 commitment、L2 anchor 和 commit height 一致。

## Splicing-in

目标：把新的 BTC L1 资产加入已有通道。

| 步骤 | 消息 / 动作                                                    | 验证点                                          |
| -- | ---------------------------------------------------------- | -------------------------------------------- |
| 1  | 读取 safety snapshot                                         | 通道 ready，无 pending，punish coverage 完整        |
| 2  | Adapter 选择或构造 L1 资产输入                                      | Agent 只提供资产、金额和授权，不直接选择 UTXO                 |
| 3  | `SplicingInReq`                                            | 声明资产、金额、当前 commit height 和是否需要发送 splicing tx |
| 4  | `SplicingInResp`                                           | 校验新容量、新余额、服务费和下一撤销材料                         |
| 5  | `SplicingInCommitSigReq` / `SplicingInCommitSigResp`       | 交换 splicing、anchor 和 commitment 签名           |
| 6  | 广播相关 L1/L2 交易                                              | BRC20 可能有 transfer inscription 和交易包          |
| 7  | `SplicingInRevokeAndAckReq` / `SplicingInRevokeAndAckResp` | 撤销旧状态，确认新承诺状态                                |
| 8  | 等待 indexer 收敛                                              | L1 funding 与 L2 ascend / anchor 可复核          |

Agent 验证：新资产进入 commitment balance；如果 indexer 尚未返回 spendable UTXO，应标记为 pending，而不是继续 unlock/lock。

## Expand

目标：把已经位于通道地址、但未纳入当前承诺状态的资产加入通道管理。

Expand 常见于三种情况：

1. 用户已经把资产转入通道地址。
2. 前序 splicing-in 在网络异常后只完成了一部分。
3. 通道恢复后发现通道地址上有属于 client 的资产。

流程与 splicing-in 类似，但客户端必须先通过 L1/L2 indexer 判断该资产是否已经 ascend。已经 ascend 的资产不能重复 anchor；未 ascend 且可证明属于通道地址的新资产，才进入 anchor 流程。

Agent 验证：expand 后 commit height 增加，资产被当前 commitment 覆盖，L2 总量没有因重复 anchor 增加。

## Unlock

目标：把通道内属于用户的资产释放到用户 L2 地址。

| 步骤 | 消息 / 动作                                            | 验证点                                                  |
| -- | -------------------------------------------------- | ---------------------------------------------------- |
| 1  | 读取 safety snapshot                                 | 通道 ready，资产在 commitment balance 中，punish coverage 完整 |
| 2  | `UnlockReq`                                        | 请求释放资产到用户 L2 地址                                      |
| 3  | `UnlockResp`                                       | Core Node 接受更新，返回本轮 revocation / next revocation 材料  |
| 4  | `UnlockCommitSigReq` / `UnlockCommitSigResp`       | 交换新承诺签名和旧状态撤销确认                                      |
| 5  | `UnlockRevokeAndAckReq` / `UnlockRevokeAndAckResp` | 完成旧状态撤销，确认 unlock 交易签名                               |
| 6  | L2 indexer 确认                                      | 用户 L2 地址出现资产，commit height 单调增加                      |

Unlock 不需要用户提供 BTC L1 fee rate 或 fee UTXO。SatoshiNet L2 可以存在 0 聪资产 UTXO。

Agent 验证：用户 L2 spendable balance 增加；通道 commitment balance 减少；最新 local commitment 与 remote commitment 都已更新。

## Lock

目标：把用户 L2 地址上的资产重新纳入通道保护。

| 步骤 | 消息 / 动作                                                    | 验证点                         |
| -- | ---------------------------------------------------------- | --------------------------- |
| 1  | 查询 L2 spendable UTXO                                       | 资产必须可花费，不能只是 pending        |
| 2  | `LockReq`                                                  | 请求把资产锁回通道                   |
| 3  | `LockResp`                                                 | 返回新承诺签名材料和下一撤销材料            |
| 4  | `LockCommitSigAndRevokeReq` / `LockCommitSigAndRevokeResp` | 交换签名并撤销旧状态                  |
| 5  | `LockAckReq` / `LockAckResp`                               | 完成本轮状态推进                    |
| 6  | 读取 safety snapshot                                         | commit height 增加，资产重新进入通道控制 |

Agent 验证：资产从用户 L2 spendable balance 转入通道 commitment balance，且旧 remote commitment 有 punish coverage。

## Lock-with-expand

目标：在通道容量不足或资产集合不足时，把用户资产重新纳入通道控制。

Lock-with-expand 是资产安全能力，不是简单的转账接口。它用于保证用户随时可以把已经在 L2 或通道地址附近的资产重新纳入通道承诺保护。

Agent 验证：操作后资产被当前 commitment 覆盖；如果需要 expand，不能重复 ascend；如果通道状态不完整，应优先进入恢复流程。

## Splicing-out

目标：把通道资产退出到 BTC L1 地址。

| 步骤 | 消息 / 动作                                                      | 验证点                                                   |
| -- | ------------------------------------------------------------ | ----------------------------------------------------- |
| 1  | 读取 safety snapshot                                           | 通道 ready，无 pending，资产在 commitment balance 中           |
| 2  | Adapter 构造退出交易包                                              | BRC20 可能需要 transfer inscription；Runes/ORDX 遵守 L1 协议规则 |
| 3  | `SplicingOutReq`                                             | 请求资产退出到 L1 地址                                         |
| 4  | `SplicingOutResp`                                            | 校验服务费、新容量、新余额和下一撤销材料                                  |
| 5  | `SplicingOutCommitSigReq` / `SplicingOutCommitSigResp`       | 交换 L1 退出、L2 descend 和承诺签名                             |
| 6  | 广播 L2 descend / de-anchor 和 L1 相关交易                          | 结果未知时进入恢复，不重复消费输入                                     |
| 7  | `SplicingOutRevokeAndAckReq` / `SplicingOutRevokeAndAckResp` | 撤销旧状态，完成本轮更新                                          |
| 8  | L1/L2 indexer 确认                                             | L2 资产减少，L1 目标地址收到资产                                   |

Agent 验证：L2 descend 与 L1 输出可关联；退出资产、金额、目标地址与用户授权一致。

## Cooperative Close

目标：双方协商关闭通道，把资产按最新状态退出。

| 步骤 | 消息 / 动作                                            | 验证点                                    |
| -- | -------------------------------------------------- | -------------------------------------- |
| 1  | 读取 safety snapshot                                 | 通道 ready，无 pending，最新 commitment 可验证   |
| 2  | `ChannelCloseReq`                                  | 请求协商关闭                                 |
| 3  | `ChannelCloseResp`                                 | Core Node 返回 closing、de-anchor 和关联交易签名 |
| 4  | `ClosingSignedReq` / `ClosingSignedResp`           | 客户端签署并确认关闭交易                           |
| 5  | 广播关闭相关交易                                           | 结果未知时查询 L1/L2 tx 可见性                   |
| 6  | `ClosingBroadcastedReq` / `ClosingBroadcastedResp` | 双方进入关闭完成或等待确认                          |
| 7  | L1/L2 indexer 确认                                   | 通道资产退出或进入用户可控地址                        |

Agent 验证：关闭前后的资产归属一致，没有遗漏通道地址上的用户资产。

## Force Close 与 Sweep

目标：当 Core Node 离线、拒绝服务或无法协商关闭时，用户单方面关闭通道。

| 步骤 | 动作                     | 验证点                                      |
| -- | ---------------------- | ---------------------------------------- |
| 1  | `stp.force_close_plan` | 返回最新 local commitment、CSV 延迟、后续 sweep 条件 |
| 2  | 广播 local commitment    | 必须是最新承诺状态                                |
| 3  | 等待 CSV 或其他 spend 条件    | 监控 peer 是否广播旧 remote commitment          |
| 4  | `stp.sweep_build`      | 构造清扫交易，默认 dry-run                        |
| 5  | 用户授权后广播 sweep          | 用户取回可清扫资产                                |

如果 Core Node 广播它持有的 commitment，用户可选择重新打开通道或清扫属于自己的通道资产。只有 Core Node 广播旧 commitment 时，用户才进入 punish 路径。

## Punish

目标：当 Core Node 广播旧 remote commitment 时，用户使用撤销材料惩罚旧状态。

| 步骤 | 动作                                | 验证点                          |
| -- | --------------------------------- | ---------------------------- |
| 1  | Watchtower 或 Agent 发现旧 commitment | txid 命中已撤销 remote commitment |
| 2  | `stp.punish_status`               | 确认惩罚材料存在且 CSV 窗口仍有效          |
| 3  | `stp.punish_build`                | 构造并 dry-run 验证 punish tx     |
| 4  | 用户授权或测试网演练授权                      | 主网必须保护用户授权边界                 |
| 5  | `stp.punish_broadcast`            | 广播惩罚交易                       |
| 6  | L1 indexer 确认                     | 通道进入 punished / closed 状态    |

测试网可以通过保留旧 commitment 和广播旧 commitment 的接口演练这个过程。主网不得开放故障注入接口。

## Reopen / Rebuild / Restore

目标：在通道关闭、状态丢失或链上结果未知后，恢复用户资产控制。

| 能力      | 流程重点                                    | 验证点                                   |
| ------- | --------------------------------------- | ------------------------------------- |
| Restore | 从本地备份、peer 状态或持久化数据恢复                   | 最新 commitment 与 punish coverage 可证明   |
| Reopen  | 旧通道关闭但通道地址仍有用户资产                        | 必要时由用户补充新 funding；不重复支付不必要费用          |
| Rebuild | channel point 或状态丢失，需要从 L1/L2 ledger 重建 | 依据 ascend / descend 记录分配资产，不重复 anchor |
| Expand  | 已在通道地址的资产未被当前 commitment 覆盖             | 纳入承诺状态并推进 commit height               |

Agent 验证：恢复后必须重新生成 safety snapshot。只要 `PUNISH_COVERAGE_UNKNOWN`、pending 不明、资产 ledger 不一致或通道状态不明，就不能继续普通价值移动。

## Agent 演练顺序

一个完整测试网演练可以按以下顺序执行：

1. 安装 SAT20 Wallet 或等价安全钱包边界。
2. 创建测试钱包，连接默认 Core Node。
3. Open 普通 client-core 通道。
4. Unlock sats，观察 commit height 增加。
5. Lock sats，确认资产回到通道保护。
6. Splicing-in Runes，等待 L1/L2 indexer 确认。
7. Unlock / Lock Runes。
8. Splicing-in BRC20，验证 transfer inscription 交易包。
9. Unlock / Lock BRC20。
10. Splicing-out 一种协议资产到 L1。
11. 导出 safety snapshot、commitment export 和 punish status。
12. 在测试网触发旧 commitment 广播，构造并广播 punish tx。
13. 使用 L1 浏览器、L2 浏览器、L1 indexer 和 L2 indexer 解释每一笔交易的作用。

演练目标不是展示余额变化，而是证明：用户持有最新退出路径，能识别旧状态，能在 peer 作恶时惩罚，能通过 indexer 独立复核资产事实。


# 第三方 STP 客户端接入指南

本文面向希望自行实现 STP 客户端的钱包、SDK、PWA adapter、CLI、后端服务和 AI Agent 工具。目标是让任何开发语言实现的客户端都能接入兼容的 Core Node。

本文只描述 STP 客户端互操作。钱包创建、助记词导入导出、密码修改、普通资产发送等能力属于 SAT20 Wallet 或 SAT20 Agent Wallet 适配器层，见 [SAT20 Agent Wallet](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/sat20-agent-wallet)。

## 接入目标

一个 STP 客户端需要完成六件事：

1. 发现并校验 Core Node。
2. 管理用户通道身份、签名和本地通道状态。
3. 构造、签名、发送和验证 STP 协议消息。
4. 查询 BTC L1 indexer 与 SatoshiNet L2 indexer。
5. 推进 open、splicing-in、unlock、lock、lock-with-expand、splicing-out、close、force close、punish 等流程。
6. 在网络异常、indexer 延迟、peer 离线和本地重启后恢复 pending 事务。

客户端把每次价值移动都回到交易、UTXO、commit height、承诺交易、ascend/descend 和 punish coverage 这些可复核证据，而不是把 Core Node 响应、余额显示或单个 indexer 响应当成最终安全证明。

## 推荐架构

| 模块                 | 职责                                                                               |
| ------------------ | -------------------------------------------------------------------------------- |
| Wallet Boundary    | 保存私钥、助记词和用户授权；可以是 PWA、硬件钱包、移动钱包或本地安全钱包                                           |
| STP Engine         | 实现 STP 消息、承诺状态、通道动作和恢复流程                                                         |
| Transaction Engine | 构造和验证 BTC L1、SatoshiNet、commitment、punish、sweep 交易                               |
| Asset Engine       | 解析 BTC、ORDX、Runes、BRC20 等资产协议和金额精度                                               |
| State Store        | 持久保存通道、commit height、承诺交易、撤销材料和 pending 事务                                       |
| Chain Query        | 查询 L1/L2 UTXO、资产、交易可见性、确认数、ascend/descend 和通道状态                                  |
| Safety Monitor     | 生成 safety snapshot、commitment export、punish status、force close plan 和 sweep plan |

AI Agent 推荐通过 SAT20 PWA Wallet Adapter 使用 STP：PWA 保存私钥和数据库，Agent 只发起受用户授权的 JSON 操作并读取安全证据。

## Core Node 发现

客户端连接 Core Node 前必须确认：

1. 钱包、Core Node、BTC L1 indexer 和 SatoshiNet L2 indexer 位于同一网络。
2. Core Node 公钥来自可信发现流程或用户显式配置。
3. Core Node 声明的协议版本、CSV 参数、服务费和能力列表可被客户端接受。
4. 客户端可以独立查询 L1/L2 状态，不能只依赖 Core Node 单方返回。

普通用户连接 Core Node 打开私人通道，不需要质押资产。质押只属于节点连接 Bootstrap Node 并准备升级为 Core Node 的路径。

推荐发现响应：

```json
{
  "protocol": "stp",
  "version": "1",
  "chain": "testnet",
  "core_node_pubkey": "02...",
  "endpoint": "https://core-node.example/stp",
  "features": [
    "open",
    "splicing-in",
    "unlock",
    "lock",
    "lock-with-expand",
    "splicing-out",
    "close",
    "force-close",
    "punish"
  ],
  "csv_delay": 1000
}
```

## 消息信封

所有需要认证的 STP 消息建议使用统一信封：

```json
{
  "protocol": "stp",
  "version": "1",
  "chain": "testnet",
  "message_type": "unlock_request",
  "request_id": "uuid-or-monotonic-id",
  "timestamp": 1760000000,
  "channel_id": "tb1q...",
  "commit_height": 12,
  "sender_pubkey": "02...",
  "payload": {},
  "signature": "hex-signature"
}
```

签名规则：

1. `signature` 之外的所有字段参与签名。
2. 序列化必须确定性，推荐 canonical JSON 或等价固定编码。
3. 接收方必须校验发送方公钥、通道身份、链 ID 和消息类型。
4. 任一消息若改变承诺状态，必须携带当前 `commit_height`。
5. 客户端必须拒绝承诺高度回退、链 ID 不匹配、签名无效或资产数量不一致的消息。

## 操作接口

面向上层钱包、CLI 或 Agent，建议 STP 客户端暴露语言无关的 JSON 操作接口。接口隐藏资产 UTXO、fee UTXO 和通道内部输入；选币和交易包构造由客户端内部完成。

### `stp.status`

查询 Core Node、通道列表、commit height、pending 事务和 indexer 同步状态。

```json
{
  "op": "stp.status",
  "chain": "testnet"
}
```

### `stp.open`

打开用户与 Core Node 的私人通道。

```json
{
  "op": "stp.open",
  "chain": "testnet",
  "core_node": "https://core-node.example/stp",
  "amount_sats": 50000,
  "memo": "optional"
}
```

客户端内部选择或构造 L1 funding 输入。普通用户 open 不需要质押资产。

### `stp.splicing_in`

把 BTC L1 资产纳入通道。

```json
{
  "op": "stp.splicing_in",
  "chain": "testnet",
  "channel_id": "tb1q...",
  "asset": "runes:EXAMPLE",
  "amount": "1000"
}
```

客户端内部选择资产输入、普通 BTC 费用输入，并在需要时构造 BRC20 transfer inscription。Agent 只传资产、金额和目标，不直接传入原始输入列表。

### `stp.expand`

把已经位于通道地址、但尚未纳入当前承诺状态的资产纳入通道管理。

```json
{
  "op": "stp.expand",
  "chain": "testnet",
  "channel_id": "tb1q...",
  "asset": "brc20:demo",
  "amount": "100"
}
```

Expand 适用于 interrupted splicing-in、rebuild 后补齐资产、或用户已把资产转入通道地址的场景。客户端必须通过 L1/L2 indexer 判断是否需要 ascend，不能重复发行聪网资产。

### `stp.unlock`

把通道资产释放到聪网个人地址。

```json
{
  "op": "stp.unlock",
  "chain": "testnet",
  "channel_id": "tb1q...",
  "asset": "ordx:demo",
  "amount": "100",
  "to": "tb1p..."
}
```

Unlock 不需要用户提供 fee rate 或 fee UTXO。SatoshiNet 没有 BTC L1 fee rate 语义；客户端内部按聪网规则处理交易费用。

### `stp.lock`

把聪网个人地址资产重新锁回通道。

```json
{
  "op": "stp.lock",
  "chain": "testnet",
  "channel_id": "tb1q...",
  "asset": "ordx:demo",
  "amount": "100"
}
```

Lock 不要求用户提供 L2 输入 UTXO。客户端内部选择可花费 L2 UTXO，并确认资产已从 pending 状态进入 spendable 状态。

### `stp.lock_with_expand`

通道容量不足时，将资产重新纳入通道控制权。

```json
{
  "op": "stp.lock_with_expand",
  "chain": "testnet",
  "channel_id": "tb1q...",
  "asset": "ordx:demo",
  "amount": "100"
}
```

这是保护用户资产控制权的重要能力。容量不足时，客户端通过 lock-with-expand 恢复通道控制权，而不是让用户手工退出 L1 再重新进入通道。

### `stp.splicing_out`

把通道资产退出到 BTC L1。

```json
{
  "op": "stp.splicing_out",
  "chain": "testnet",
  "channel_id": "tb1q...",
  "asset": "brc20:demo",
  "amount": "100",
  "to_l1_address": "tb1p..."
}
```

客户端内部选择普通 BTC fee 输入。对 BRC20，客户端应在需要时构造 transfer inscription 和相关交易包；对 Runes 和 ORDX，客户端必须遵守对应 L1 协议转移规则。

### `stp.close`

协商关闭或强制关闭通道。

```json
{
  "op": "stp.close",
  "chain": "testnet",
  "channel_id": "tb1q...",
  "mode": "cooperative"
}
```

`mode` 可以是 `cooperative` 或 `force`。强制关闭必须返回 commitment txid、CSV 延迟和后续 sweep 条件。

## 安全接口

上层 Agent 或钱包 UI 必须能读取安全证据，而不是只读取余额。

| 接口                      | 用途                                                                    |
| ----------------------- | --------------------------------------------------------------------- |
| `stp.safety_snapshot`   | 返回 channel point、commit height、承诺交易、余额、CSV、punish coverage、pending 状态 |
| `stp.commitment_export` | 导出当前 local / remote commitment 的只读校验材料                                |
| `stp.punish_status`     | 查询已撤销 remote commitment 的惩罚覆盖                                         |
| `stp.punish_build`      | 对指定旧 commitment 构造并 dry-run 验证惩罚交易                                    |
| `stp.punish_broadcast`  | 经用户授权后广播惩罚交易                                                          |
| `stp.force_close_plan`  | 返回当前可广播 local commitment 和后续 sweep 条件                                 |
| `stp.sweep_build`       | CSV 到期后构造 sweep 交易；默认 dry-run，授权后广播                                   |
| `stp.transaction`       | 查询 pending STP 事务、相关 txid、下一步等待条件和错误状态                                |

这些接口不得导出私钥、助记词或未授权的 revocation secret。

## 成功响应

价值移动操作的成功响应不能只返回 `ok:true`。最低应包含：

| 字段                                             | 说明                                                        |
| ---------------------------------------------- | --------------------------------------------------------- |
| `transaction_id`                               | 后续轮询事务状态的稳定句柄                                             |
| `channel_id`                                   | 操作作用的通道                                                   |
| `status`                                       | `BROADCASTED`、`READY_DEGRADED`、`CONFIRMED`、`FAILED` 等标准状态 |
| `tx_ids`                                       | 已知 L1/L2/commitment/punish 交易 ID                          |
| `commit_height_before` / `commit_height_after` | 如果通道状态前进，应返回高度变化                                          |
| `next_check`                                   | 下一步应等待的确认、indexer 状态或事务查询                                 |
| `safety`                                       | 操作后的安全摘要，或要求立即调用 `stp.safety_snapshot`                    |

Agent 根据这些字段继续轮询和验证，而不是只根据余额变化判断操作成功。

## Commitment Balance 与 Spendable UTXO

客户端必须区分：

1. Commitment balance：最新承诺交易中已经分配给某一方的资产余额。
2. Spendable UTXO：L1 或 L2 indexer 已确认、当前可以作为下一笔交易输入使用的 UTXO。

刚 splicing-in 或 expand 的资产可能已经进入 commitment balance，但对应 L1 funding 或 L2 anchor 仍未确认。此时安全快照可以证明双方已经签署新状态，但客户端不能把资产作为 unlock / lock 的输入。

如果 commitment balance 已包含资产，而 indexer 尚未返回可花费 UTXO，客户端应返回 `ASSET_PENDING_CONFIRMATION` 或等价状态。Agent 的正确动作是继续轮询 reservation 和 L1/L2 indexer。

## 资产规则

| 资产    | 客户端要求                                                |
| ----- | ---------------------------------------------------- |
| 白聪    | 区分 L1 dust / fee 约束与 L2 0 聪 UTXO 能力                  |
| ORDX  | 按 `bindingSat` 计算绑定聪；`ordx:o` 类型对象不进入聪网              |
| Runes | L2 不需要绑定聪；L1 输出仍遵守 BTC 规则                            |
| BRC20 | 支持 transfer inscription；没有可用 transfer UTXO 时由客户端内部构造 |

如果一个 UTXO 同时携带多种资产，STP 只 ascend 操作中明确指定的一种资产。未指定资产不进入本次 L2 守恒校验。

## 结果未知恢复

Timeout、EOF、连接中断、服务重启或 indexer 暂未收敛，都应视为结果未知。

统一流程：

1. 停止重发同一请求，锁定相关输入。
2. 保存请求、reservation、txid、channel id、asset、amount 和错误文本。
3. 查询 `stp.transaction`。
4. 查询相关 L1/L2 txid 是否可见。
5. 查询 Core Node channel status、commit height、channel point 和 pending 状态。
6. 如果任一交易可见、任一方状态前进或 reservation 存在，继续轮询原事务。
7. 只有双方仍在同一旧安全状态、无 pending、相关交易都不可见，才允许重新做 preflight 并重试。

这条规则适用于 open、splicing-in、splicing-out、unlock、lock、close、force close 和 punish。

## 发布前互操作测试

第三方客户端至少应在测试网完成：

1. Open 普通 client-core 通道。
2. Sats unlock / lock 推进 commit height。
3. Runes splicing-in、unlock、lock。
4. BRC20 splicing-in、unlock、lock。
5. ORDX 小额资产 splicing-in。
6. Splicing-out 至少一种协议资产。
7. 结果未知恢复，不重复消费输入。
8. Safety snapshot、commitment export、punish status、force close plan。
9. 测试网旧 commitment 广播与 punish 演练。
10. 客户端重启后恢复 pending 事务和安全材料。

验收细节见 [STP 第三方客户端实现验收清单](/xie-yi-yu-an-quan/stp/implementation-checklist)。


# STP 第三方客户端实现验收清单

> 本文面向准备自行实现 STP 客户端的钱包团队、SDK 团队和 AI Agent 适配器。它不是某个代码库的实现说明，而是一份协议互操作验收清单：只要客户端满足这些能力，就可以用任意开发语言接入兼容的 Core Node。

## 最小可用客户端

一个最小可用 STP 客户端必须具备以下能力：

| 能力    | 验收标准                                                     |
| ----- | -------------------------------------------------------- |
| 钱包密钥  | 能生成或导入用户密钥，并用用户密钥签名 STP 消息和交易                            |
| 服务发现  | 能获得 Core Node 网络、服务地址、公钥、节点 ID 和能力列表                     |
| 消息认证  | 能对 STP 请求和响应做确定性序列化、签名、验签和链 ID 校验                        |
| L1 查询 | 能查询 BTC L1 UTXO、资产、交易可见性、确认数和原始交易                        |
| L2 查询 | 能查询 SatoshiNet UTXO、资产、交易可见性、通道地址状态和 ascend / descend 记录 |
| 交易引擎  | 能构造、校验、签名和广播 BTC L1 交易、SatoshiNet 交易、承诺交易、惩罚交易和清扫交易      |
| 状态存储  | 能持久保存通道、承诺高度、最新承诺交易、已撤销状态惩罚材料和未完成事务                      |
| 恢复流程  | 重启后能恢复 pending 事务，不因本地进程退出而丢失通道控制能力                      |
| 安全接口  | 能向上层 Agent 返回安全快照、承诺交易、惩罚覆盖和强制关闭计划                       |

如果客户端只能发起 open / unlock / lock，但不能导出安全快照、不能证明惩罚覆盖、不能恢复 pending 事务，则它不能被视为完整 STP 客户端。

## 必须持久化的数据

STP 客户端不能只保存钱包余额。每个通道至少要持久保存：

| 数据                               | 用途                              |
| -------------------------------- | ------------------------------- |
| channel id / channel address     | 识别通道和 2-of-2 控制地址               |
| client pubkey / core node pubkey | 校验消息身份、重建通道脚本                   |
| channel point                    | 当前 BTC L1 通道 outpoint，承诺交易必须花费它 |
| funding / splicing UTXO 集合       | 判断哪些 L1 资产已由通道管理                |
| commit height                    | 判断状态是否单调推进，拒绝回退                 |
| local commitment tx              | peer 离线时本方可广播的最新退出交易            |
| remote commitment tx             | 监控 peer 广播的承诺交易是否为旧状态           |
| local / remote balance           | 当前承诺状态下双方资产归属                   |
| CSV delay                        | 强制关闭后清扫本方输出的等待窗口                |
| revoked remote commitment 索引     | 识别 peer 旧状态作弊                   |
| punish tx 或可构造材料                 | 对旧 remote commitment 执行惩罚       |
| pending reservation              | 结果未知或未确认事务的恢复入口                 |
| 关联 L1 / L2 txid                  | 重启后继续轮询交易可见性和确认                 |

持久化顺序也很重要。客户端在释放旧状态撤销材料前，必须已经保存新承诺状态、最新 local commitment、remote commitment 和对应的安全材料。否则进程崩溃会破坏用户的链上退出能力。

## Agent 安全能力

AI Agent 通过客户端或 PWA adapter 提供的只读或受控接口判断通道安全，而不是依赖猜测：

| 接口                      | 最低返回内容                                                                                                               |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `stp.status`            | 钱包网络、Core Node 状态、通道列表、channel status、commit height                                                                  |
| `stp.safety_snapshot`   | channel point、commit height、承诺交易是否存在、余额、CSV、Merkle roots、punish coverage、`l2_spendable_balance`、`l2_pending_balance` |
| `stp.commitment_export` | 当前 local / remote commitment 的 txid、hex 或结构化交易、余额和校验材料                                                               |
| `stp.punish_status`     | 已撤销 remote commitment 的 punish tx 列表、是否 verified、是否 broadcastable                                                    |
| `stp.punish_build`      | 给定旧 commitment txid，构造并验证惩罚交易，不暴露 revocation secret                                                                  |
| `stp.punish_broadcast`  | 广播已验证惩罚交易                                                                                                            |
| `stp.force_close_plan`  | 当前可广播 local commitment、CSV delay、后续 sweep 条件                                                                         |
| `stp.sweep_build`       | CSV 到期后构造、签名、验证 sweep tx；`broadcast:false` dry-run，`broadcast:true` 授权后广播                                            |

Agent 只有在 `stp.safety_snapshot` 返回 `READY_SAFE`，且 punish coverage 为 `NO_REVOKED_REMOTE_STATE` 或 `COVERED` 时，才应发起普通价值移动。`PUNISH_COVERAGE_UNKNOWN` 和 `PUNISH_COVERAGE_MISSING` 都必须阻止 splicing、unlock、lock 和 close。

`READY_DEGRADED` 只能用于只读跟踪。它可能表示承诺交易已经存在，但 L1 funding 尚未确认、peer 状态尚未收敛或 adapter 仍在恢复。第三方客户端不得把 `READY_DEGRADED` 当作 unlock、lock、splicing、close 或 punish drill 的许可。

## 价值移动前置检查

每次 open 之后的价值移动前，客户端必须完成以下检查：

1. 网络一致：钱包、Core Node、BTC L1 indexer、SatoshiNet indexer 都在同一网络。
2. 通道可用：channel status 为 ready，并且没有 pending reservation。
3. 承诺高度：本地 commit height 没有回退；如可查询 peer 状态，应确认双方高度一致或差异可解释。
4. 承诺交易：local commitment 和 remote commitment 都存在，并且输入指向当前 channel point。
5. 余额一致：承诺交易输出、资产根、local / remote balance 与请求后的资产变化一致。
6. 惩罚覆盖：已撤销 remote commitment 均有 verified / broadcastable punish tx，或当前明确没有已撤销 remote commitment。
7. 输入未锁定：adapter 内部选择的输入未被其他 pending 事务占用。
8. L2 可花费性：unlock/lock 的目标资产必须已经位于 `UtxosL2` / `l2_spendable_balance`；仍在 `pendingUtxosL2` / `l2_pending_balance` 的资产只能等待 adapter/indexer 收敛。
9. Fee 输入合法：协议资产 splicing-out 由 adapter 内部选择普通 BTC L1 fee 输入；除白聪 unlock 的内部例外外，不使用通道地址 UTXO 作为发起方 fee。
10. 用户授权：主网操作必须让用户确认资产、金额、目标地址、手续费和操作类型。
11. 事务持久化：在进入广播或最终承诺交换前，pending 事务和相关 txid 已持久化。

## 资产规则

STP 客户端必须按资产协议分别处理 UTXO 和金额：

| 资产    | 规则                                                                                                     |
| ----- | ------------------------------------------------------------------------------------------------------ |
| 白聪    | BTC L1 有 dust 和 fee 约束；SatoshiNet L2 没有 BTC dust 约束                                                    |
| ORDX  | 必然绑定聪，必须根据资产数量和 `bindingSat` 计算需要多少聪；Ordinals NFT 不 ascend 到聪网                                         |
| Runes | L2 不需要绑定聪，可以由 `Value=0` 的 SatoshiNet UTXO 携带；L1 转移输出仍受 BTC 输出规则约束                                      |
| BRC20 | L2 不需要绑定聪；L1 splicing-in/out 可能涉及 transfer inscription 和 commit/reveal，transfer UTXO 由 adapter 内部选择或构造 |

如果一个 L1 UTXO 中同时携带多种资产，STP splicing-in 只处理接口参数明确指定的资产。未指定资产不会进入聪网，也不进入第三方客户端的 L2 余额预期。

面向 Agent 的 splicing-in 接口隐藏资产输入选择。当前客户端内部选币会优先避开包含多种可 ascend 资产的 UTXO；如果必须使用这类 UTXO，需要在操作预览中提示未指定资产不会 ascend。

客户端不得把 wallet summary 中的余额直接当成可消费 UTXO。特别是 BRC20 和 Runes：余额存在不等于已经有可直接用于当前 STP 操作的 transfer UTXO。BRC20 splicing-in 应区分 adapter 创建 fresh transfer inscription 和直接消费已有 transfer UTXO 两种模式；没有明确支持 direct transfer UTXO 时，不应盲目把 existing transfer UTXO 传入。

## 结果未知恢复

STP 客户端必须把 timeout、连接中断、服务暂不可用等网络异常视为“结果未知”，而不是明确失败。

结果未知时的统一流程：

1. 停止重发同一请求，锁定相关 UTXO。
2. 保存请求 JSON、reservation、txid、channel id、asset、amount 和错误文本。
3. 查询 pending reservation；如果存在，继续轮询原事务。
4. 查询相关 BTC L1 / SatoshiNet txid 是否可见。
5. 查询 Core Node 的 channel status、commit height、channel point 和 pending 状态。
6. 如果 tx 可见、任一方状态前进或 reservation 存在，继续轮询和恢复原事务。
7. 只有双方仍在同一个旧安全状态、无 pending reservation、相关 tx 都不可见，才允许重新做 adapter preflight 并重试。

这条规则适用于 open、close、splicing-in、splicing-out、unlock 和 lock。广播之后的未知网络结果必须优先按“可能成功”处理；早期协商阶段的未知结果也要先比较双方状态和 tx 可见性，不能直接重试。

如果客户端在状态切换中遇到未知网络结果，并且无法证明新承诺状态已经完成，安全接口必须返回 `PUNISH_COVERAGE_UNKNOWN` 或 `READY_DEGRADED`，而不是让 Agent 继续普通价值移动。

## 通道恢复验收

客户端应支持以下恢复动作：

| 恢复动作                             | 适用场景                                                                                   | 验收标准                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `stp.restore`                    | 本地丢失状态，但 peer 或备份仍有最新通道                                                                | 恢复后 safety snapshot 可证明最新承诺和惩罚覆盖                                        |
| `stp.reopen`                     | 通道关闭或缺失，但 channel ledger 证明这是已有 client-core channel，通道地址仍有属于 client 的资产或需要补充新的 funding | 不要求质押资产；必要时由用户钱包创建新 L1 funding；funding 确认且 local/core 均 ready 后才能继续价值移动 |
| `stp.rebuild`                    | L1 channel point 已变化，但资产在 SatoshiNet ledger 中已有 anchor 证据                              | 不重复创建 opening anchor，按 ledger 恢复通道                                      |
| `stp.expand`                     | L1 资产已在通道地址，但未纳入当前承诺状态                                                                 | 资产进入承诺状态，commit height 前进                                               |
| interrupted splicing-in recovery | L1 funding UTXO 已 ascended，但客户端/peer 没有正确完成 splicing-in                                | 复用已有 L2 anchor 输出，不重复 anchor                                            |

No-anchor rebuild 必须依赖 SatoshiNet channel ledger。客户端要能判断某个 L1 UTXO 是否已经对应 ascend，或者是否来自 descending v2 返回通道地址的余额输出。无法判断时宁可拒绝自动恢复，也不能重复发行聪网资产。

## 与 Core Node 的互操作验收

一个第三方客户端接入 Core Node 前，至少要在测试网完成：

| 测试                                | 通过条件                                                                  |
| --------------------------------- | --------------------------------------------------------------------- |
| open                              | 普通 client 连接 Core Node 成功打开通道，不要求质押资产                                 |
| safety snapshot                   | open 后能读取 local / remote commitment、channel point、commit height 和 CSV |
| sats unlock / lock                | commit height 单调增加，余额变化正确                                             |
| Runes splicing-in / unlock / lock | Runes 能进入通道，并能在 L2 个人地址和通道之间往返                                        |
| BRC20 splicing-in / unlock / lock | BRC20 能进入通道，并能在 L2 个人地址和通道之间往返                                        |
| splicing-out                      | 至少一种协议资产能退出到 BTC L1；fee 不足时 adapter 能返回明确错误，并引导用户补充普通 BTC fee 资金      |
| 结果未知恢复                            | 在广播或 peer ack 返回未知网络结果时不重复消费 UTXO，轮询或恢复流程能收敛                          |
| punish coverage                   | 每次状态推进后能证明旧 remote commitment 有惩罚覆盖                                   |
| force close plan                  | peer 离线时能给出可广播 local commitment 和 CSV 后 sweep 条件                      |
| restart recovery                  | 客户端重启后 pending reservation、承诺交易和安全快照仍可恢复                              |

完成以上测试后，客户端才能被视为具备基础互操作能力。正式主网发布前，还必须增加长时间运行、reorg、索引器延迟、peer 离线、重复请求、数据库恢复和 wallet 授权取消等测试。

## 主网发布门槛

主网客户端至少要满足：

1. 私钥和助记词永远在钱包安全边界内，不由 Agent 保存。
2. 主网价值移动需要用户逐项确认。
3. 每个通道状态更新前后都能生成安全快照。
4. 数据库崩溃或进程退出后，最新承诺交易和 pending 事务不丢失。
5. `PUNISH_COVERAGE_UNKNOWN`、`PUNISH_COVERAGE_MISSING`、commit height 回退、余额不一致、签名无效都会阻止新的价值移动。
6. 所有测试网故障注入接口都不会进入主网构建。
7. Agent 可以解释资产当前位置、可退出路径、惩罚覆盖和剩余风险。

STP 的主网用户体验可以很简单，但客户端内部不能简化安全模型。用户可以不理解 RSMC、承诺交易和惩罚交易；Agent 和钱包必须理解，并且能持续证明这些安全条件成立。


# SatoshiNet


# SatoshiNet 协议概览

SatoshiNet，中文名聪网，是 SAT20 生态中的比特币原生扩展网络。它的目标不是替代比特币主网，而是在不放弃用户资产控制权的前提下，为 BTC 主网资产提供更低成本、更快确认、更适合合约和 AI Agent 自动化操作的流通环境。

## 定位

聪网可以理解为一个面向比特币资产的并行执行网络：

1. 资产入口来自 BTC L1。
2. 资产事实由 L1/L2 indexer 记录和复核。
3. 资产跨层控制由 STP 通道提供。
4. 日常交易、合约和应用在 SatoshiNet 上执行。
5. 用户在异常情况下仍应能通过 STP 的承诺交易、强制关闭、清扫和惩罚路径保护资产。

因此，聪网不是托管桥，也不是独立发行一套与 BTC 无关的资产。它的核心承诺是：资产来自比特币，安全边界回到比特币，应用体验发生在聪网。

## 与闪电网络的关系

聪网继承了闪电网络最关键的安全基础：RSMC 通道、承诺交易、撤销和惩罚机制。不同的是，聪网不以 HTLC 路由支付为中心，而是把 RSMC 通道与并行 UTXO 网络结合起来，用 STP 支持多资产、动态容量和聪网合约。

这种设计带来几个差异：

1. 通道可以通过 splicing-in / splicing-out 调整容量和资产集合。
2. 通道支持 BTC、ORDX、Runes、BRC20 等主网资产。
3. 资产进入聪网后可以在 L2 UTXO 和合约中流通。
4. 钱包和 AI Agent 可以通过安全快照、承诺交易和惩罚覆盖验证资产控制权。

## 节点角色

| 节点             | 职责                                                                       |
| -------------- | ------------------------------------------------------------------------ |
| Bootstrap Node | 辅助 Core Node 发现和准入                                                       |
| Core Node      | 覆盖 Mining Node 全部功能，并提供 STP 服务，与钱包建立私人通道，协签通道交易，维护通道状态，并运行或配置 L1 indexer |
| Mining Node    | 参与聪网出块，不提供 STP 服务                                                        |
| Wallet Client  | 普通用户钱包或轻客户端，连接 Core Node，持有私钥、通道状态和安全材料                                  |

普通用户连接 Core Node 打开私人通道时，不需要质押资产。只有节点准备成为 Core Node，并连接 Bootstrap Node 参与网络服务时，才涉及核心节点准入要求。

## 资产模型

聪网使用增强型 UTXO（enUTXO）表达资产。与 BTC L1 普通 UTXO 只直接表达聪数量不同，enUTXO 可以显式携带资产信息，例如 ORDX、Runes、BRC20 或其他经过 indexer 识别并通过 STP 进入聪网的资产。

这个模型的目标是：

1. 让钱包和浏览器直观看到 UTXO 中包含的资产。
2. 让合约和交易验证可以直接读取资产信息。
3. 让 L1/L2 的资产证据链可以从 UTXO、ascend、descend 和通道状态中追踪。
4. 让 AI Agent 能判断某份资产是否在个人地址、通道地址、合约地址或 pending 状态中。

白聪在 BTC L1 仍受 dust 和手续费约束；在聪网上，UTXO 可以携带 0 聪资产，尤其适用于 BRC20 和 Runes 这类不需要绑定聪的资产。ORDX 则必然绑定聪，需要按 `bindingSat` 计算承载关系。

## Indexer

Indexer 是聪网资产事实的基础。

L1 indexer 负责解析 BTC 主网上的 UTXO、sat range、Ordinals、Runes、BRC20、ORDX、确认状态、mempool 和 reorg。Core Node 运行时需要配置并依赖自己的 L1 indexer，因此 Core Node 网络会推动 L1 indexer 的事实分布式部署。

L2 indexer 集成在聪网节点中，负责解析 SatoshiNet 上的 UTXO、ascend、descend、通道、合约、交易结果和资产状态。运行聪网节点的参与者会随节点维护自己的 L2 状态视图，因此 L2 indexer 本质上随节点网络分布。

聪网的资产安全需要 STP + indexer 一起成立：STP 提供控制权和退出路径，indexer 提供资产事实和跨层证据。

## 共识与执行

聪网基于 btcd 风格的 UTXO 系统演进，并围绕 SAT20 资产、通道和合约做扩展。它采用更适合 L2 执行环境的共识与出块机制，目标是降低交易成本、提升确认速度，并让资产和合约可以在比特币生态语义下运行。

聪网的长期方向不是让 BTC L1 承担复杂计算，而是让 BTC L1 保持最终结算和资产根基，聪网承担更高频、更复杂、更适合应用的执行。

## 通道合约、智能合约与 GAS

聪网的合约能力分为两类：通道合约和智能合约。

通道合约更靠近 L1/L2 连接处。它主要用于管理公共资产池，并协调用户发起的跨层动作，例如公共资产穿越、资产发射、分发、退款和提现。通道合约不同于私人 STP 通道：合约池中的资产不属于通道任意一方，也不提供私人 channel 那种用户承诺交易和惩罚旧状态机制。

智能合约运行在 SatoshiNet 全局执行环境中，依赖合约地址、VM 状态、canonical Result TX、state root 和 GAS。它面向更开放的应用开发，例如 AMM、限价单、预测、EVM 合约和自然语言合约。

GAS 是聪网合约执行、交易处理和生态激励的经济入口。围绕 GAS 的资产、使用、激励和分配机制，将成为聪网生态吸引开发者、交易平台、投资机构和 BTC 资产社区的重要部分。

通道合约见 [通道合约](/xie-yi-yu-an-quan/channel-contracts/channel-contracts)，智能合约细节见 [智能合约协议](/xie-yi-yu-an-quan/smart-contracts/contracts)，网络费用与 GAS 见 [网络经济](/wang-luo-jing-ji/network-economics)。

## 安全模型

聪网安全来自多层组合：

1. BTC L1 提供资产来源、UTXO 结算和通道最终退出边界。
2. STP 提供 RSMC 承诺交易、撤销、CSV 延迟、强制关闭和惩罚能力。
3. L1/L2 indexer 提供资产事实、ascend/descend、通道状态和合约状态的可复核证据。
4. SatoshiNet 节点网络验证 L2 交易、UTXO 和合约执行。
5. 钱包和 AI Agent 通过安全快照、承诺交易导出、惩罚覆盖和链上查询判断资产是否仍在用户控制下。

用户可以不理解所有底层细节，但钱包和 Agent 必须理解，并在价值移动前给出可验证的安全结论。

## 生态方向

聪网面向几类关键参与者：

1. BTC 原生资产用户：获得更快、更便宜、更可验证的资产流通路径。
2. 钱包和交易平台：接入统一 indexer、STP 和 SatoshiNet 交易能力。
3. 开发者：在比特币资产之上构建合约、交易、支付和 AI Agent 应用。
4. 资产发行方：把 ORDX、Runes、BRC20 等资产带入更活跃的应用网络。
5. AI Agent：帮助用户理解风险、验证证据并安全执行资产操作。

聪网的目标是成为比特币生态中最重要的原生扩展网络之一：资产来源于比特币，安全回到比特币，应用在聪网上繁荣。


# DKVS

DKVS（Distributed Key-Value Store）是 SatoshiNet 内置的、由数据所有者控制的小数据存储与同步层。它为钱包、账户恢复、RGB11 状态备份、邮箱、服务发现和应用配置提供统一的签名 record 模型。

DKVS 不是通用多主数据库，也不是 Bitcoin 或 SatoshiNet 的共识状态。它解决的是：**负责保存某条数据的节点，如何验证写入者、原子接受更新，并最终收敛到同一个有效状态。**

## 核心原则

1. 普通 path 只有一个 owner 或 authority。
2. `Seq` 管理单个 key 的版本，`PathGeneration` 管理整个 logical path 的变更顺序。
3. 写入通过 CAS 或 batch-CAS 提交；任一前置条件失败时不部分落库。
4. record 的 key、value、费用证明、时间、sequence 和 path generation 都由签名覆盖。
5. 网络数据通过 SatoshiNet 原生 P2P 传播；`FREE_LOCAL` 数据只属于接收节点。
6. Wallet SDK 只通过 `dkvsManager` 管理 transport、replica、同步、generation 和 outbox。
7. DKVS 不自动合并账户管理、RGB11 或其他领域状态；领域层必须定义自己的冲突策略。

## Key 与 logical path

DKVS key 使用路径格式：

```
/<namespace>/<segments...>
```

当前主要 namespace：

| Namespace                                | 用途                     | Logical path / 权限                                   |
| ---------------------------------------- | ---------------------- | --------------------------------------------------- |
| `/personal/<account_id>/<module>/...`    | 用户个人数据、账户管理、RGB11 head | 按 module 划分 owner-exclusive path；仅 account owner 可写 |
| `/blob/<account_id>/<blob_key>`          | 加密快照或较大对象              | 完整 blob key 为独立 owner-exclusive path                |
| `/mail/<receiver>/msg/<sender>/<msg_id>` | 离线消息                   | sender 子 path 为 shared-append；receiver 可删除          |
| `/mail/<receiver>/share/...`             | Guardian/share 数据      | receiver owner-exclusive                            |
| `/name/<name>`                           | 名称资料                   | 当前 DID/NS authority 可写                              |
| `/svc/<service>/...`                     | 服务配置与发现                | 当前 service authority 可写                             |
| `/tmp/...`                               | relay、ACK 等短期数据        | local-only，必须设置受限 TTL                               |
| `/sys/...`                               | 系统参数                   | 配置的 system signer 可写                                |

`/personal/<account_id>` 下按 module 划分 path，例如账户管理和 RGB11 使用不同 path，避免无关业务共享同一个 generation 和写锁。

### PathMode

| Mode                  | 语义                                             |
| --------------------- | ---------------------------------------------- |
| `owner_exclusive`     | 由 account ID 等确定 owner；正常情况下只有一个 active writer |
| `authority_exclusive` | owner 由 DID、service 或 system authority 决定      |
| `shared_append`       | 多个写入者只能创建各自唯一 key，不共享 mutable value            |
| `local_only`          | 仅当前 endpoint 保存，不参与网络同步和 PathMeta              |

## DKVSRecord v1

每条 record 包含：

```
Version
Key
Value
PubKey
Signature
Seq
PathGeneration
IssueTime
TTL
ExpiryHeight
FeeProof
Flags
```

### 大小限制

* 普通 value 最大 16 KiB。
* `/blob` value 最大 1 MiB。
* blob 是一条完整 record，不再使用 manifest/chunk 拆分协议。
* 一个 batch 最多 64 个 mutation，record 总编码大小最多 8 MiB。
* key 最大 256 字节，segment 最大 64 字节。

应用不应把 DKVS 当作通用文件存储。大文件应使用专门的数据分发系统，DKVS 只保存必要的小对象、加密快照或引用。

### Seq 与 PathGeneration

正常更新必须满足：

```
new.Seq = current.Seq + 1
```

同一 path 的每次有效 mutation 使用连续的：

```
new.PathGeneration = current_path_generation + 1
```

同一个 batch 内，record 按 canonical key 顺序分配连续 `PathGeneration`。远端节点从 owner 已签名的 record 中读取 generation，不能按本地接收次数重新计数。

### IssueTime 与确定性选择

Wallet SDK 使用节点返回的 `server_time_ms` 构造单调时间：

```
IssueTime = max(server_time_ms, previous_issue_time + 1)
```

异常情况下同 key 出现多个候选时，选择顺序是：

1. 更大的 `Seq`；
2. 相同业务内容的 retention renewal；
3. 更大的 `IssueTime`；
4. `RecordHash` 字节序。

该规则保证最终确定性，但不承诺多设备并发修改的业务语义都被保留。

## PathMeta 与状态同步

网络可比较的 PathMeta 包含：

```
Path
Generation
StateRoot
ActiveRecords
ActiveTotalSize
MinExpiryHeight
ViewHeight
```

`StateRoot` 是 path 当前有效 record 和 delete floor 的确定性摘要。它用于判断两个节点是否需要同步，不是链上承诺，也不是 Merkle membership proof。

比较规则：

1. generation 较小的一方需要同步；
2. generation 和 root 相同，path 已收敛；
3. generation 相同但 root 不同，执行完整 path reconciliation；
4. endpoint 的 generation 低于客户端已确认状态时，该 endpoint 被视为 stale，不能继续写入。

完整 path snapshot 会携带 PathMeta、有效 records、delete floors 和 `server_time_ms`。接收方必须完整验证并在一个本地 DB batch 中替换 confirmed state。

## CAS 与 batch-CAS

单 key CAS 至少绑定：

```
signed_record
expected_path_generation
expected_record_hash 或 expect_absent
```

batch-CAS 用于同一个 owner 的多 key 原子提交，例如：

* 账户恢复包的 envelope、share、questions 和 manifest；
* RGB11 的 encrypted snapshot 与 wallet head；
* 应用需要同时更新的多个相关 key。

batch-CAS 的保证范围是接收 RPC 节点的本地数据库：

* 全部校验成功后一次提交；
* 任一 mutation 失败时 `applied=0`；
* 多 path 按 canonical 顺序加锁；
* 完全相同的 record/batch 重试是幂等成功；
* 只存在部分 record 时返回 conflict，不自动补齐剩余 mutation。

它不是跨节点线性一致事务，也不支持跨 owner 事务。

## 费用与保留策略

### AUTOPAY

`AUTOPAY` 是可跨节点传播的主要费用模式。节点读取 `autopay.tc` 合约状态，验证：

* 合约模板、服务名称、fee asset 和 recipient；
* signer 对应的委托地址；
* active delegate 状态；
* 每区块额度和余额；
* 当前 active record 数量是否超过容量。

容量按满尺寸 record 计算：

```
max_records = floor(amount_per_block / full_record_fee_per_block)
```

### FREE\_LOCAL

`FREE_LOCAL` 用于开发、临时缓存和明确的本节点备份：

* 必须带有效 FREE\_LOCAL fee proof；
* 只写入当前 endpoint；
* 不通过 P2P relay；
* 不进入网络 PathMeta、checkpoint 或 path snapshot；
* TTL、记录数、字节数和 blob key 数受节点策略限制；
* 新设备只有连接到同一个 endpoint 才能恢复；
* 切换 endpoint 后不能把它显示为“网络备份”。

当前默认本地策略通常允许有限 TTL、每 signer 有界记录数和有界总字节数。主网是否允许 FREE\_LOCAL 由节点策略决定。

### 其他 proof

`ONESHOT` 和 `LEASE` 已保留紧凑编码，但完整结算验证仍属于后续阶段。

## P2P 与 endpoint-local overlay

Relayable record 通过 SatoshiNet 原生 DKVS 消息传播。远端节点重新验证：

* key 和 namespace；
* owner/authority；
* 签名与 fee proof；
* sequence、PathGeneration 和 delete floor；
* 大小、TTL、expiry 和 quota。

当收到 generation gap 时，节点不能猜测中间状态，必须标记 path stale 并执行完整 path sync。

`FREE_LOCAL` 不进入网络 snapshot。Wallet SDK 在完成网络 path snapshot 后，会从同一 endpoint 读取 local-only records，并合并为 endpoint-scoped overlay。该 overlay 不参与网络 `StateRoot`。

## Wallet SDK 的 dkvsManager

领域模块不直接持有 DKVS transport。`dkvsManager` 统一负责：

* endpoint client 与 endpoint identity；
* per-path 锁和 readiness；
* confirmed replica 与 local-only overlay；
* sequence、PathGeneration 和单调 IssueTime；
* CAS/batch-CAS；
* exact signed batch outbox；
* path refresh、watch 和 change notification；
* typed error 映射。

写入流程：

```
等待 path ready
→ 获取 per-path 锁
→ 读取 confirmed replica / PathMeta
→ 分配 seq 与 PathGeneration
→ 签名 exact record/batch
→ 保存 exact outbox
→ 提交 CAS/batch-CAS
→ 使用写响应更新 replica、PathMeta 和 outbox
→ 通知领域模块
```

重试必须复用完全相同的签名 bytes，不重新生成 sequence、generation、time 或签名。

稳定错误码包括：

```
DKVS_WRITE_CONFLICT
DKVS_STALE_GENERATION
DKVS_STALE_ENDPOINT
DKVS_PERMISSION_DENIED
DKVS_INVALID_SEQUENCE
DKVS_PATH_DIVERGED
DKVS_LOCAL_ONLY_ENDPOINT_MISMATCH
DKVS_QUOTA_EXCEEDED
DKVS_RECORD_NOT_FOUND
```

调用方应使用 typed error 或稳定错误码，不应解析英文错误文本。

## 账户管理

账户管理使用 `/personal/<account_id>/account/...`：

* recovery package 使用四记录原子 batch；
* managed wallet state 使用加密 envelope 和单调 revision；
* 显式同步会先刷新远端 path；
* CAS 冲突、stale generation、path divergence 和 invalid sequence 使用有界重试；
* 钱包重命名、账户元数据和新增子账户由账户管理层按字段重放；
* 删除钱包属于 inventory mutation，会折叠同钱包更早的 metadata mutation；
* root wallet 不能删除；
* 错误 secret 或错误 root mnemonic 不能恢复状态。

这些字段级合并属于账户管理领域逻辑，不是 DKVS 的通用多主保证。

## RGB11

RGB11 使用独立的 `/personal/<account_id>/rgb11/...` 和 `/blob/<account_id>/...`：

* encrypted snapshot 与 wallet head 使用一个 batch-CAS；
* head 是单调 revision，并绑定 snapshot state hash 和 operation ID；
* 同 endpoint 的 FREE\_LOCAL 备份可供新设备恢复；
* active AUTOPAY 可升级为 relayable backup；
* AUTOPAY 查询失败但节点支持 FREE\_LOCAL 时，回退到临时备份；
* stale writer 必须返回 head conflict，不能覆盖较新的远端状态；
* RGB 资产有效性最终由客户端验证和 Bitcoin evidence 决定，DKVS 只保存加密状态和传输数据。

更多内容见 [RGB11 资产与 Wallet SDK](/xie-yi-yu-an-quan/rgb11)。

## E2E 验收范围

Wallet SDK E2E 使用本地启动的 bootstrap、core 和 miner 节点，覆盖：

* AUTOPAY name owner rotation、mailbox append/tombstone 和三节点同步；
* FREE\_LOCAL 同 endpoint 恢复与跨 endpoint 隔离；
* account recovery package 原子发布；
* account management 激活、恢复、边界条件和双设备字段级合并；
* RGB11 固定地址 invoice、encrypted backup、同 endpoint 恢复和 stale writer；
* CAS、PathGeneration、PathMeta、typed error 与 P2P 收敛。

连接已有公网测试网、消耗真实测试资产或修改公共网络状态的测试使用独立 build tag，不进入默认测试集合。

## 明确边界

DKVS v1 不提供：

* 任意多主 CRDT；
* 跨账户事务；
* 跨节点线性一致提交；
* quorum、BFT 或链上 commit certificate；
* FREE\_LOCAL 跨 endpoint 恢复；
* 通用大文件存储；
* ONESHOT/LEASE 的完整结算实现；
* 自动理解并合并任意业务对象。

应用应把 DKVS 当作可验证、owner-controlled、最终一致的小数据层，而不是关系数据库或全局共识数据库。


# RGB11 资产与 Wallet SDK

RGB11 是基于 Bitcoin L1、采用客户端验证模型的资产协议。SAT20 Wallet SDK 将 RGB11 合约、资产状态、UTXO 证明、收发流程和本地恢复能力内聚在专用的 `rgb11Manager` 中，并通过统一的钱包接口提供给 PWA、桌面钱包和其他应用。

RGB11 资产的有效性最终由合约、consignment、一次性封印、Bitcoin 交易证据和客户端验证结果决定。Indexer 可以提供交易和 UTXO 证据，但不能替代 RGB11 客户端验证，也不能凭索引结果创造资产余额。

> 当前实现首先完成 Bitcoin L1 钱包闭环。RGB11 资产进入 SatoshiNet 的 STP 流程仍在开发中；在完整 STP 支持上线前，SDK 会把需要 STP 的路径视为不可用。

## 1. 协议版本与源码基线

### 1.1 采用的 RGB 版本

SAT20 的 `rgb11` 协议空间明确锁定在 **RGB 0.11.1 系列**。当前 Go 实现所采用的共识、operations、invoicing、schema 和 PSBT/API 冻结基线为 **`0.11.1-rc.11`**。

版本关系必须按以下方式理解：

* SAT20 协议名：`rgb11`；
* 协议目标：RGB `0.11.1`；
* 冻结的 Rust 共识与数据格式基线：`0.11.1-rc.11`；
* 当前代码不会自动跟随 RGB 上游最新分支；
* RGB `0.12` 具有共识级和数据结构变化，不属于 `rgb11` 的兼容升级；未来接入时必须使用独立协议空间 `rgb12`。

因此，文档中“RGB11”不是泛指所有 RGB 版本，而是特指上述冻结版本集合。

### 1.2 官方 Rust 源码与精确 commit

SAT20 Go 实现以以下冻结的上游 Rust 代码为协议和互操作参考。所有链接均固定到精确 commit，不能用浮动的 `master`、`main` 或 semver 范围替代。

| 领域                                  | 上游版本                                     | 上游源码                                                                                                                                               |
| ----------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| RGB 共识、operation ID、seal、commitment | `rgb-consensus 0.11.1-rc.11`             | [`rgb-protocol/rgb-consensus@44e79963`](https://github.com/rgb-protocol/rgb-consensus/commit/44e79963aa4603270eee9aa112ef07a512345e98)             |
| Operations、consignment、invoicing    | `rgb-ops` / `rgb-invoicing 0.11.1-rc.11` | [`rgb-protocol/rgb-ops@5308b9d4`](https://github.com/rgb-protocol/rgb-ops/commit/5308b9d46c91857513ff5be2459992264687632b)                         |
| PSBT utilities 与 API                | `rgb-psbt-utils 0.11.1-rc.11`            | [`rgb-protocol/rgb-api@8d448f46`](https://github.com/rgb-protocol/rgb-api/commit/8d448f46c866d44ca0495ad0e924e57d9fd294dd)                         |
| 官方 schema：NIA、IFA、CFA、UDA           | `rgb-schemas 0.11.1-rc.11`               | [`rgb-protocol/rgb-schemas@c5e43e98`](https://github.com/rgb-protocol/rgb-schemas/commit/c5e43e987d18a2398d5f5f6c78629480fd792abd)                 |
| Strict Encoding                     | `rgb-strict-encoding 1.0.2`              | [`rgb-protocol/rgb-strict-encoding@7698a5e9`](https://github.com/rgb-protocol/rgb-strict-encoding/commit/7698a5e96a2a27d5bfa4cd3560da0e8af8e4a18a) |
| Strict Types                        | `rgb-strict-types 1.0.2`                 | [`rgb-protocol/rgb-strict-types@09b58e6c`](https://github.com/rgb-protocol/rgb-strict-types/commit/09b58e6c2db25cef8bdb15e33b8654530607b972)       |

### 1.3 钱包互操作参考

钱包流程的主要外部 oracle 是：

* [`RGB-Tools/rgb-lib`](https://github.com/RGB-Tools/rgb-lib)，版本 `0.3.0-beta.7`，固定 commit [`538f2abaa67d7ce96be32d94092e8f1b9e3ea38e`](https://github.com/RGB-Tools/rgb-lib/commit/538f2abaa67d7ce96be32d94092e8f1b9e3ea38e)。它用于核对钱包状态、Esplora 同步、invoice、consignment、签名、接收和余额流程。
* [`RGB-WG/rgb`](https://github.com/RGB-WG/rgb) 官方命令行钱包，固定 tag `v0.11.1-alpha.3`、commit [`a9bba35ceed7e0c4bc4e477f663ab022d7b0a23e`](https://github.com/RGB-WG/rgb/commit/a9bba35ceed7e0c4bc4e477f663ab022d7b0a23e)。它只用于人工核对 CLI 命令面和钱包派生路径。

必须注意：`RGB-WG/rgb v0.11.1-alpha.3` 使用的是 alpha.3 crate 格式，不能作为 `0.11.1-rc.11` consignment/parser 的发布门禁。rc.11 文件互操作以冻结的 rc.11 Rust crates 和 `rgb-lib 0.3.0-beta.7` 为准。

### 1.4 SAT20 Go 实现

SAT20 使用独立的 Go 实现：

* 源代码：[`sat20-labs/rgb11`](https://github.com/sat20-labs/rgb11)；
* Wallet SDK adapter：[`sat20-labs/sat20wallet`](https://github.com/sat20-labs/sat20wallet/tree/main/sdk/wallet/rgb11)；
* 精确上游版本、commit、crate checksum 和翻译映射：[`UPSTREAM_MANIFEST.json`](https://github.com/sat20-labs/rgb11/blob/main/UPSTREAM_MANIFEST.json)；
* 官方互操作说明：[`OFFICIAL_INTEROP.md`](https://github.com/sat20-labs/rgb11/blob/main/OFFICIAL_INTEROP.md)。

`github.com/sat20-labs/rgb11` 是对冻结 Rust 基线的**独立 Go 重实现**，不是 RGB 上游官方 Go SDK，也不是把 Rust 库包装成 Go FFI。共识结构、Strict Encoding、ID、seal、anchor、consignment 和 PSBT 字段必须与冻结上游一致；Wallet SDK、DKVS、Indexer 和 PWA 的接入属于 SAT20 adapter 层。

当前 manifest 记录了部分逐文件翻译关系，例如：

```
rgb-strict-encoding/rust/src/traits.rs
  -> strict_encoding/encoder.go, strict_encoding/decoder.go

rgb-consensus/src/commit_verify/digest.rs
  -> consensus/tagged_hash.go

rgb-consensus/src/operation/commit.rs
  -> consensus/id.go

rgb-consensus/src/seals/txout/blind.rs
  -> seals/blind.go

rgb-ops/src/containers/consignment.rs
  -> consignment/armor.go
```

Go 实现只有在冻结的 Rust differential vectors、官方 parser round-trip 和钱包互操作门禁通过后，才能声明对应能力已兼容。

## 2. 资产身份

RGB11 资产有两个不同层次的标识：

* **Contract ID / official asset ID**：协议级唯一身份，是验证资产的最终依据；
* **SAT20 AssetName**：钱包、UI 和资产列表使用的可读索引名称。

当前 Wallet SDK 为新发行或导入的合约生成确定性 AssetName：

```
rgb11:<type>:<normalized_ticker>_<contract_fingerprint>
```

例如：

```
rgb11:f:usdt_k7m3q9x2d4
```

其中：

* `rgb11` 是协议名；
* `f` 表示同质化资产；
* ticker 会转为小写、限制字符和长度；
* fingerprint 默认取 Contract ID 的 10 字符确定性摘要；
* Contract ID 始终保存在 ticker 扩展信息中，不能仅凭短 ticker 判断资产身份。

短 ticker 只适合显示。未经主资产注册或发行方认证时，UI 应显示带 fingerprint 的名称；只有明确完成认证后，才可以把 `usdt` 等短名作为主要显示名称。

## 3. Wallet SDK 边界

外层 `wallet.Manager` 只暴露 RGB11 领域接口，协议实现由内部 `rgb11Manager` 负责。其职责包括：

* 合约发行、导入和注册；
* consignment 解码与客户端验证；
* RGB11 UTXO、allocation proof 和余额投影；
* invoice、地址接收能力和发送准备；
* PSBT 构造、Tapret carrier 签名和交易广播；
* relay、ACK/NACK 和 pending transfer 生命周期；
* DKVS 加密备份、恢复和多设备冲突检测；
* RGB11 UTXO 锁定与重建。

外层钱包不应重新实现 RGB11 内部函数，也不应直接操作 RGB11 engine store、projection store 或 DKVS transport。

## 4. 发行与导入

### 4.1 发行

`IssueRGB11Asset` 根据发行请求构造 RGB11 合约，并完成：

1. 选择 Bitcoin L1 carrier UTXO；
2. 构造资产分配和合约状态；
3. 生成并验证 RGB11 合约；
4. 保存合约、证明和 ticker 扩展信息；
5. 锁定承载 RGB11 状态的 UTXO；
6. 更新本地资产投影和备份状态。

首版发行入口开放 NIA、IFA 和 UDA；CFA 可以按冻结的官方 schema 导入和验证，但当前 SDK/PWA 不提供 CFA 发行入口。

发行前后的余额都来自客户端可验证状态，不从 L1 Indexer 的普通资产 ticker 接口合成。

### 4.2 导入

导入合约时，SDK 必须先解析和验证合约文件，再注册：

* Contract ID；
* schema；
* canonical AssetName；
* 原始 ticker、normalized ticker 和 fingerprint；
* issuer/control metadata；
* 可选 reject-list 或 policy adapter 信息；
* 当前验证状态。

无效、损坏或与已有状态冲突的合约不能进入可用资产列表。

## 5. 接收方式

### 5.1 Witness invoice

Witness 接收使用当前钱包子账户的固定 P2TR 地址脚本。连续创建多个 invoice 时：

* 每个 invoice 有独立 `RequestID`、金额和过期时间；
* witness script 可以保持为当前子账户的固定地址脚本；
* 收到 consignment 后，仍必须通过其 Contract ID、seal、allocation 和 Bitcoin witness 证据完成验证。

固定地址只解决被动接收和地址稳定性，不降低客户端验证要求。

### 5.2 Blind seal

Blind 模式使用一次性封印。SDK 会为待接收状态保留 carrier UTXO，并使用 `pending-rgb` 原因锁定，直到接收完成、失败、取消或过期。

### 5.3 配置化地址接收

应用可以为一个 Bitcoin 地址发布 RGB11 receive capability/profile，使发送方能够解析该地址对应的接收能力，并通过 DKVS mailbox 投递加密 consignment。该流程适合被动接收，不要求接收方在线生成一次性 invoice。

地址/profile 只描述接收能力和投递位置，不代表接收方已经接受资产。最终接受仍由本地 consignment 验证和 ACK 决定。

## 6. 发送、Relay 与 ACK

标准发送流程为：

1. 解析 invoice 或接收地址能力；
2. 检查资产、余额、UTXO 锁和最小确认数；
3. 构造 transition、consignment、PSBT 和 change seals；
4. 保存 pending transfer；
5. 向接收方投递 consignment；
6. 接收方验证后返回 ACK 或 NACK；
7. ACK 满足策略后广播 Bitcoin 交易；
8. 跟踪确认数并更新 allocation、余额和 UTXO 锁。

SDK 支持三类传输接口：

* SAT20/DKVS relay 与 mailbox；
* 配置化地址投递；
* 标准 RGB JSON-RPC proxy。

公共 relay record 只包含传输定位和校验所需的信息。私有 seal disclosure、完整本地 consignment、签名交易和 change seal 不写入公共 relay record 或 wallet head。

ACK 不是资产有效性的替代证明。接收方只有在本地客户端验证通过后才能签发 ACK；发送方也必须校验 ACK 与 transfer、recipient 和 relay record 的绑定关系。

## 7. UTXO 与余额模型

RGB11 状态绑定 Bitcoin UTXO。Wallet SDK 对相关 UTXO 使用两个锁定原因：

```
rgb          已确认承载 RGB11 状态
pending-rgb  正在参与待完成的接收或发送流程
```

钱包启动、切换钱包、切换子账户或恢复快照后，会根据 projection store 和 allocation proof 重建锁定集合。

RGB11 余额由本地有效 allocation 汇总。以下情况不会形成可用余额：

* 缺少 allocation proof；
* consignment 验证失败；
* witness 交易或 outpoint 无法确认；
* Contract ID、schema 或 assignment 不匹配；
* 状态被 reject-list/policy 判定为不可接受；
* 本地 RGB11 状态标记为 inconsistent/broken。

## 8. DKVS 钱包备份

RGB11 钱包状态使用独立 DKVS path，不与账户管理或其他模块共享 generation。核心对象为：

```
/personal/<account_id>/rgb11/<wallet_id>/head
/blob/<account_id>/<rgb11_snapshot_key>
```

实际 key 由 SDK 的 `RGB11WalletHeadPath` 和 `RGB11WalletSnapshotBlobKey` 统一生成。

### 8.1 Head 与 snapshot

* snapshot 包含 RGB11 engine records、projection records 和 ticker metadata；
* snapshot 在写入 DKVS 前使用当前钱包公钥加密；
* head 包含 wallet ID、sequence、state hash 和 operation ID；
* head 与 snapshot 通过同一 `dkvsManager` batch-CAS 原子写入目标节点；
* 恢复时先验证 head，再解密 snapshot，并检查 state hash、wallet ID、account index 和 engine build ID。

DKVS 只负责可靠保存和同步加密状态，不能替代 RGB11 资产验证。

### 8.2 保存模式

优先级为：

1. 当前钱包存在有效 DKVS AUTOPAY 委托时，使用可传播的付费保存；
2. AUTOPAY 不可用或查询失败，但当前 endpoint 明确启用 FREE\_LOCAL 时，回退到临时保存；
3. 两种模式都不可用时，返回保存策略错误。

`FREE_LOCAL` 的含义必须明确：

* 只保存在当前 endpoint；
* 不通过 P2P relay；
* 不进入网络 PathMeta、checkpoint 或 snapshot；
* 只能从同一 endpoint 恢复；
* UI 不得把它显示为“全网备份”。

### 8.3 多设备和冲突

同一 RGB11 wallet 同一时间只支持一个 active writer。另一个设备可以读取和恢复，但在写入前必须同步到最新 head。

当两个设备基于同一旧 head 分别修改并提交时，后提交者会收到 head conflict、DKVS write conflict 或 stale generation。SDK 不自动合并两个 RGB11 状态；用户或应用必须选择最新有效状态并重新执行未提交操作。

## 9. 安全边界

RGB11 钱包集成依赖以下独立检查：

* RGB11 合约和 schema 验证；
* consignment 完整性和状态转换验证；
* seal 与 allocation proof 验证；
* Bitcoin 交易、outpoint、script 和确认数证据；
* 钱包私钥对 PSBT/Tapret carrier 的正确签名；
* DKVS record 身份、签名、sequence、PathGeneration 和费用证明；
* relay/ACK 与 transfer ID、recipient、txid/vout 的绑定。

任何一层验证失败，都不能通过其他层的索引结果或网络响应绕过。

当前实现不把一般化的发行方冻结能力定义为 RGB11 协议共识规则。可选 reject-list 或 policy adapter 只影响当前钱包是否接受某个状态；其具体治理和冻结语义需要由资产发行方案单独定义。

## 10. 当前测试覆盖

Wallet SDK 已包含真实本地三节点 E2E，覆盖：

* 固定地址 witness invoice；
* 独立 RequestID；
* RGB11 head + encrypted snapshot 原子保存；
* 同 endpoint 新设备恢复；
* FREE\_LOCAL 跨 endpoint 隔离；
* AUTOPAY 查询失败回退 FREE\_LOCAL；
* stale writer/head conflict；
* 非法 amount 和接收 mode；
* 既有 issue、transfer、proxy、address delivery、ACK 和 allocation 单元/集成测试。

这些测试使用本地 SatoshiNet bootstrap、core、miner 节点，不依赖公共测试网或外部 RGB regtest 服务。

Go 引擎仓库还保留冻结 Rust/Go differential vectors、官方 rc.11 parser round-trip，以及 `rgb-lib` 双向文件交换与 regtest 互操作证据。具体门禁和证据位置见 `UPSTREAM_MANIFEST.json` 与 `OFFICIAL_INTEROP.md`。

## 11. 主要 Wallet SDK API

常用入口包括：

```
IssueRGB11Asset
ImportRGB11Contract / ImportRGB11ContractFile
CreateRGB11Invoice
PrepareRGB11Transfer
PrepareConfiguredRGB11AddressTransfer
DeliverAndBroadcastConfiguredRGB11AddressTransfer
AcceptRGB11Consignment
ValidateRGB11Consignment
RefreshRGB11State
GetRGB11State
GetRGB11AssetBalance
ListRGB11Outputs
SyncRGB11WalletState
RestoreLatestRGB11WalletState
ActivateRGB11WalletState
RebuildRGB11Locks
```

应用层应使用这些领域 API，不直接拼装 DKVS key、record、sequence、PathGeneration 或 RGB11 内部存储对象。


# Channel Contracts


# 通道合约

通道合约（Channel Contract）是聪网早期用于协调 BTC L1 与 SatoshiNet L2 动作的公共协议设施。它与私人 STP 通道不同，也与 SatoshiNet 智能合约不同。

私人 STP 通道管理的是两个 peer 之间的资产控制关系，通道中的资产归属可以由双方最新承诺交易判定。通道合约管理的是公共资产池或公共业务状态，通道合约中的资产不属于通道任意一方，而应理解为属于聪网公共设施；其中可能包含用户寄存的资产，用户可以按合约规则取回。

## 核心定位

通道合约的主要目的，是协调用户发起的 L1/L2 动作：

1. 用户把 BTC L1 资产发送到合约通道地址。
2. 合约识别这笔用户发起的动作。
3. 合约在 SatoshiNet 上执行对应分发、发射、退款、提现或状态更新。
4. 当需要从 L2 回到 L1 时，合约协调 descend / de-anchor 和 L1 输出。
5. 合约记录每个用户动作、结果交易和可查询状态。

通道合约不是为了给公共池资产提供私人通道那种承诺交易安全。公共池资产没有“属于本 peer 或 remote peer”的二分归属，也没有用户可单方面广播的最新 commitment 来取回整个池子。它更像一个由协议约束的跨层公共设施：用户通过明确动作进入，合约按规则处理，结果由 L1/L2 交易和 indexer 事实验证。

## 与私人 STP 通道的区别

| 维度   | 私人 STP 通道                              | 通道合约                                               |
| ---- | -------------------------------------- | -------------------------------------------------- |
| 资产归属 | 资产属于通道两端 peer，可由最新承诺状态分配               | 资产属于公共设施或合约池；用户寄存部分按合约规则取回                         |
| 安全机制 | RSMC、承诺交易、撤销、CSV、惩罚、强制关闭               | 协议规则、合约状态、共同签名、L1/L2 交易和 indexer 证据                |
| 用户退出 | 用户持有最新 commitment，可单方面 force close     | 用户按合约规则 withdraw、refund、close 或等待合约处理结果            |
| 主要动作 | open、splicing、unlock、lock、close、punish | deploy、invoke、deposit、withdraw、launch、refund、close |
| 目标   | 保护单个用户与 Core Node 之间的资产控制权             | 为公共资产穿越、资产发射、公共池状态提供跨层协调                           |

因此，通道合约文档不能把通道合约描述成“用户资产仍由承诺交易保护的业务层”。这是私人 STP 通道的安全语义，不是通道合约的资产语义。

## 与智能合约的区别

通道合约和智能合约也不同。

| 维度   | 通道合约                                             | 智能合约                                       |
| ---- | ------------------------------------------------ | ------------------------------------------ |
| 主要位置 | L1/L2 连接处，围绕通道地址和跨层动作运行                          | SatoshiNet 全局执行环境                          |
| 主要目的 | 协调 L1/L2 资产动作，处理公共设施中的用户请求                       | 在 L2 上运行可编程应用状态机                           |
| 状态来源 | 合约运行状态、invoke history、L1/L2 交易、ascend/descend 记录 | 合约 VM 状态、canonical Result TX、区块 state root |
| 资产控制 | 公共池资产和用户寄存资产按合约规则处理                              | 合约地址资产由 VM 执行结果授权花费                        |
| 适合场景 | 资产穿越、资产发射、公共跨层设施                                 | AMM、限价单、预测、EVM、自然语言合约等应用                   |

核心进化在于验证范围：通道合约主要由通道两端节点围绕通道状态、共同签名和 L1/L2 动作推进；聪网智能合约则进入全网共识，由整个聪网验证合约调用、canonical Result TX 和 contract state root。

当前 PWA 市场中的 AMM 和限价单仍属于 L2 市场通道合约能力，不属于聪网智能合约。测试网中同时存在智能合约模板 AMM / LimitOrder 和 EVM `ConstantProductAMM` / `LimitOrderBook` 样本，它们只能从 PWA `工具 -> 智能合约` 入口交互，用于验证全网共识合约路径。

随着 SatoshiNet 智能合约能力成熟，部分应用逻辑可以逐步进入智能合约中的模板合约、EVM 合约或 Agent 合约实现。通道合约仍应保留那些真正需要连接 L1/L2、协调跨层动作、管理公共设施资产池的能力，尤其是 `transcend.tc` 和 `launchpool.tc` 这类能力。

## 核心通道合约

### `transcend.tc`

`transcend.tc` 是资产穿越通道合约。它面向任意资产的 L1/L2 进出，尤其用于公共穿越场景。

它的核心语义包括：

1. 支持指定资产在 BTC L1 与 SatoshiNet L2 之间进入和退出。
2. 用户发起 `deposit` 时，把 L1 资产交给通道合约识别和处理，并在 L2 获得对应分发。
3. 用户发起 `withdraw` 时，在 L2 提出退出请求，合约协调 L2 资产销毁或锁定，并在 L1 给用户输出资产。
4. 合约需要维护公共池中 L1 未 ascend 的 UTXO、L2 可用资产和必要的 descend / de-anchor 动作。
5. 如果 L2 公共池中已有足够资产，合约可以直接向用户分发；如果不足，才需要进一步协调 ascend。
6. 如果 L1 可用 UTXO 不足以支持 withdraw，合约需要先协调 descend / de-anchor，形成可用于 L1 输出的资产。

`transcend.tc` 的重点不是交易撮合，也不是用户私人通道安全，而是公共资产穿越能力：让用户发起跨层动作，并让合约协调 L1/L2 之间的资产平衡。

### `launchpool.tc`

`launchpool.tc` 是资产发射通道合约。它把资产部署、铸造、L2 anchor、用户 mint、达到发射水位后的分发，以及失败或关闭时的退款组织成一个跨层流程。

它的核心语义包括：

1. 部署资产发射参数，例如资产协议、ticker、总量、单地址限制、发射比例、预留比例、绑定聪参数等。
2. 根据资产协议执行 L1 部署和铸造动作，例如 ORDX、BRC20、Runes。
3. 将铸造结果引入聪网，形成发射池可管理的 L2 资产。
4. 用户在 SatoshiNet 上发起 mint / 参与动作，合约记录每个用户的有效和无效输入。
5. 当达到发射条件或到期条件后，合约执行 launch，把资产按规则分发给参与用户、部署者或基金会相关地址。
6. 对无效输入或失败场景，合约执行 refund。
7. 如果发射失败或合约关闭，合约按规则把剩余资产退回部署者或相关参与者。

`launchpool.tc` 体现了通道合约的另一个特点：它不是单纯 L2 应用，也不是单纯 L1 发行工具，而是把 L1 资产协议、L2 发射状态、用户参与记录和跨层资产动作串成一个公共流程。

## 公共资产池语义

通道合约管理的资产应按以下方式理解：

1. 合约池中的公共资产不属于通道任意 peer。
2. 用户转入合约的资产，在合约规则确认前处于寄存或 pending 状态。
3. 用户可取回的资产，由合约记录、invoke history、L1/L2 交易和 indexer 结果共同证明。
4. 合约利润、保留资产、发射底池、退款资产等，都需要按合约规则区分。
5. 合约池不能用私人通道的 local / remote balance 语义解释。

这也是通道合约与私人 channel 的根本区别。私人 channel 的核心问题是“双方谁拥有多少资产”；通道合约的核心问题是“公共设施如何根据用户动作和协议规则处理资产”。

## 用户发起原则

通道合约动作通常由用户发起，而不是由 Core Node 单方面决定。

用户动作可以发生在 BTC L1，也可以发生在 SatoshiNet L2：

1. L1 动作：用户向合约通道地址发送资产，或携带合约调用参数。
2. L2 动作：用户向合约地址提交 invoke 交易。
3. 合约处理：合约根据当前区块、用户输入、资产状态和合约运行状态接受或拒绝动作。
4. 结果动作：合约生成分发、退款、withdraw、launch、close 等结果交易。

Core Node 或 peer 可以参与签名、广播、监控和推进状态，但用户动作和合约规则才是合约处理的起点。

## 验证要求

钱包、区块浏览器、indexer 和 AI Agent 在解释通道合约时，应能验证：

1. 合约类型和合约参数。
2. 合约通道地址。
3. 用户 invoke / deposit / withdraw / mint 输入。
4. 用户输入对应的 L1/L2 txid、vout、资产、金额和确认状态。
5. 合约是否接受该输入，拒绝原因是什么。
6. 合约生成的结果交易，例如 anchor、de-anchor、launch、refund、withdraw。
7. 用户当前可领取、已领取、已退款或仍 pending 的资产状态。
8. 合约池中的公共资产、用户寄存资产、保留资产和利润是否能被区分。

AI Agent 将通道合约余额按公共池、用户寄存、可退款、可提现、已分发或 pending 等状态解释，而不是简单视为某个用户可直接控制的余额。

## 与后续模板合约的关系

早期 `.tc` 模板中包含了 AMM、swap、limit order 等业务逻辑。但从协议演进看，这些更像 SatoshiNet 应用层逻辑，未来更适合由智能合约中的模板合约实现。

通道合约应重点保留那些真正需要连接 L1/L2、协调跨层动作、管理公共设施资产池的能力。当前最核心的通道合约是：

1. `transcend.tc`：公共资产穿越。
2. `launchpool.tc`：资产发射和跨层分发。

其他交易类、做市类和应用类逻辑，应优先纳入智能合约体系，用 canonical Result TX、state root 和 GAS 来提供更清晰的 L2 共识边界。

## 参考

* SAT20Labs 关于通道合约的说明：<https://x.com/SAT20Labs/status/2062547908852080933>
* SAT20Labs 关于通道合约的说明：<https://x.com/SAT20Labs/status/1951655721600532693>


# Smart Contracts


# 智能合约协议

本文定义聪网智能合约的通用协议。智能合约不同于 [通道合约](/xie-yi-yu-an-quan/channel-contracts/channel-contracts)：通道合约主要用于管理公共资产池，并协调用户发起的 L1/L2 跨层动作；智能合约则运行在 SatoshiNet 全局执行环境中。

具体合约类型的差异见：

1. [模版合约](/xie-yi-yu-an-quan/smart-contracts/template)
2. [EVM合约](/xie-yi-yu-an-quan/smart-contracts/evm)
3. [自然语言合约](/xie-yi-yu-an-quan/smart-contracts/agent)

## 协议边界

聪网智能合约是运行在聪网上的可编程共识状态机。合约状态由聪网节点维护，资产来源和资产结算由聪网UTXO模型表达。

智能合约不同于 [通道合约](/xie-yi-yu-an-quan/channel-contracts/channel-contracts)。通道合约面向公共资产池和 L1/L2 协调，典型能力是公共资产穿越与资产发射；智能合约基于链上交易、合约VM状态、canonical `CONTRACT_RESULT`和区块级state root。智能合约发起的资产转移不需要私钥签名，必须由VM执行结果授权。

## 合约类型

聪网智能合约第一阶段包含三类：

1. 模版合约：由聪网节点源码内置的Go runtime执行，对应`ContractTypeTemplate`。
2. EVM合约：由EVM执行器执行，对应`ContractTypeEVM`。
3. 自然语言合约：由AI Agent支持的自然语言协议合约，对应`ContractTypeAgent`，第一阶段优先支持预测型Agent合约，以单CoreNode Agent模式进入聪网合约结果流程。

## 核心模型

1. UTXO是链上资产的唯一来源。
2. VM是合约状态机。
3. `CONTRACT_DEPLOY`创建合约。
4. `CONTRACT_INVOKE`调用合约。
5. `CONTRACT_RESULT`结算VM产生的资产转移。
6. `COINBASE_CONTRACT_STATE_ROOT`在coinbase中承诺区块执行后的合约state root。
7. 所有节点必须确定性重放合约执行。
8. 合约UTXO不通过传统私钥签名解锁，而由VM执行结果授权花费。

## 地址规则

主网合约地址格式：

```
ca + version + type + hash
```

测试网合约地址格式：

```
tc + version + type + hash
```

字段定义：

1. `ca`为主网合约地址前缀。
2. `tc`为测试网合约地址前缀。
3. `version`当前为`1`。
4. `type`表示合约类型。
5. `hash`由合约类型定义长度和计算方式。

## 交易类型

合约相关交易分为四类：

1. `CONTRACT_DEPLOY`
2. `CONTRACT_INVOKE`
3. `CONTRACT_RESULT`
4. `COINBASE_CONTRACT_STATE_ROOT`

合约交易通过OP\_RETURN携带部署、调用、结果和state root的协议envelope：

```
OP_RETURN | SAT20_MAGIC_NUMBER | CONTENT_TYPE | CONTENT
```

当前内容类型：

```
CONTENT_TYPE_CONTRACT_DEPLOY     = OP_DATA_31
CONTENT_TYPE_CONTRACT_INVOKE     = OP_DATA_32
CONTENT_TYPE_CONTRACT_RESULT     = OP_DATA_33
CONTENT_TYPE_CONTRACT_STATE_ROOT = OP_DATA_34
```

`CONTRACT_INVOKE`的OP\_RETURN只应携带action、nonce、gas limit，以及无法从交易输出推导的非经济参数。资产名称、资产数量、satoshi数量、gas/funding输出等经济参数以Call TX中转入合约地址的输出为准，不应在OP\_RETURN中重复表达。若某类调用需要滑点、最小可接受输出、deadline、证明hash或calldata等非经济参数，可以放入invoke payload。

如果一笔交易没有合约OP\_RETURN，但包含输出到有效合约地址的输出，该输出可以被合约解释为默认调用。默认调用不携带显式action和参数，其业务语义由对应合约类型和合约实例定义。

部署交易可以因为合约内容较大而使用多个合约OP\_RETURN分片。普通交易和合约调用交易不应滥用OP\_RETURN；除协议明确允许的部署分片外，交易中的OP\_RETURN数量应受mempool策略限制，当前普通路径不应超过4个OP\_RETURN。

## 合约关闭和利润分配

智能合约支持统一的关闭语义。`close`调用只能由合约deployer发起；具体合约可以在关闭前先按自身状态规则返还有明确归属的资产，例如未成交订单、LP份额或其他用户可识别权益。

关闭完成后，合约管理资产中剩余且没有明确用户归属的部分视为合约利润，按deployer 60%、bootstrap 40%的比例分配。合约地址上超出合约runtime管理记录的资产，不参与合约业务结算，关闭时统一转给bootstrap，由bootstrap后续处理。

该规则适用于模版合约、EVM合约和自然语言合约。不同合约类型只能决定哪些资产在关闭前具有明确用户归属，不能改变最终无归属利润和非管理资产的通用处理方式。

## CONTRACT\_DEPLOY

`CONTRACT_DEPLOY`用于部署合约。

部署交易必须包含合约类型、合约内容、版本、deployer、随机值和gas limit。不同合约类型可以定义自己的部署payload，但必须能确定性生成合约地址和初始状态。

每个有效部署都必须在同一区块内由canonical `CONTRACT_RESULT`记录部署结果和state root。

## CONTRACT\_INVOKE

`CONTRACT_INVOKE`用于调用合约。

调用交易必须有一个输出转入被调用合约地址，作为本次调用的gas/funding输出。该输出用于：

1. 绑定Call TX和Result TX。
2. 承载本次调用转入合约的资产。
3. 预付合约调用费用。
4. 在需要结算时作为`CONTRACT_RESULT`输入。

被调用合约地址不写入OP\_RETURN。节点必须通过Call TX中输出到合约地址的输出确定被调用合约。

显式`CONTRACT_INVOKE`只能调用一个合约，且对当前被调用合约只能有一个gas/funding输出。这样可以避免同一调用内出现多个经济输入来源，确保Call TX、Result TX、caller和退款目标都能确定性解析。默认调用没有显式payload，可以按每个合约输出分别触发对应合约的默认行为。

调用发起者身份由调用交易最后一个输入对应的前序输出地址解析得到。共识路径不使用witness中的公钥、签名公钥或其他可替换字段作为caller/invoker身份来源；如果最后一个输入的前序输出不可获得或无法解析地址，调用无效。

## CONTRACT\_RESULT

`CONTRACT_RESULT`用于记录VM执行结果并结算资产转移。

规则：

1. `CONTRACT_RESULT`由出块节点构造，外部提交的`CONTRACT_RESULT`不进入mempool。
2. `CONTRACT_RESULT`必须位于它结算的`CONTRACT_DEPLOY`和`CONTRACT_INVOKE`之后。
3. 普通部署和调用的`CONTRACT_RESULT`必须与它结算的交易出现在同一区块。
4. 如果结算`CONTRACT_INVOKE`，对应Call TX转入合约地址的gas/funding输出必须作为Result TX输入。
5. Result TX输出必须与节点本地重放得到的资产转移结果一致。
6. Result TX允许批量结算多个执行项，批量顺序必须与协议执行顺序一致。
7. 注册触发器到期后可以在没有同区块普通合约交易的情况下产生`CONTRACT_RESULT`。验证节点必须通过Result TX花费的合约UTXO识别合约类型和合约地址，并基于上一状态、当前区块高度和确认时间重放到期触发器；无法证明触发器真实存在、已经到期且仍有效的孤立Result TX无效。

`CONTRACT_RESULT`的OP\_RETURN只写入执行状态摘要和结果数量。call id、合约地址、输入输出、完整trace和资产转移明细由区块交易、本地重放和节点索引器推导。

## State Root

合约state root写入coinbase交易，不修改区块头结构。

区块内可以同时包含模版合约、EVM合约和Agent合约的deploy/invoke/result。当前执行顺序为：

1. 模版合约交易执行和Result TX生成。
2. EVM合约交易执行和Result TX生成。
3. Agent合约交易执行和Result TX生成。
4. 将模版合约state root、EVM合约state root和Agent合约state root合成统一的contract state root。
5. 在coinbase中写入最终contract state root。

## Gas和费用

智能合约使用统一的gas资产支付费用。

费用类型：

1. 合约调用费用。
2. VM执行费用。
3. Result TX打包费用。
4. 触发器执行费用。

费用规则：

1. gas费用由调用方或合约自身承担。
2. gas price第一阶段采用协议固定值。
3. gas费用归出块节点。
4. gas/funding输出中的费用部分不进入合约资产余额。
5. 执行成功且没有资产转移的调用可以不生成Result TX。
6. 需要资产转移、退款、revert或out of gas的调用必须生成Result TX。

## Canonical Result TX

所有节点必须按相同规则构造和验证canonical Result TX。

输入选择规则：

1. 优先包含被结算`CONTRACT_INVOKE`转入合约地址的gas/funding输出。
2. 只选择当前合约地址下的可用UTXO。
3. UTXO按资产名称分组。
4. 同一资产内按确认高度、txid、vout排序。
5. 从排序后的UTXO列表头部开始选择，直到满足资产转移和费用需求。
6. 累计金额足够后停止选择。

输出规则：

1. 先输出VM结果指定的资产转移。
2. 同一执行项产生多个输出时，按VM定义的顺序输出。
3. 找零输出回同一个合约地址。
4. 找零输出位于资产输出之后。
5. OP\_RETURN输出位于最后。

## 区块构造和验证

出块节点构造区块时：

1. 选择普通交易。
2. 选择合约相关交易。
3. 按区块内顺序执行合约部署和调用。
4. 检查已注册且在当前区块到期的触发器，即使本区块没有其他合约交易，也必须主动执行到期触发器。
5. 为需要结算的执行项生成canonical Result TX。
6. 计算最终contract state root。
7. 在coinbase中写入contract state root并领取gas费用。

验证节点验证区块时：

1. 独立解析区块内合约交易。
2. 按协议顺序重放合约执行。
3. 对没有同区块deploy/invoke的Result TX，根据其输入花费的合约UTXO确定合约类型，并重放对应到期触发器。
4. 构造本地canonical Result TX。
5. 比较区块中的Result TX和本地推导结果。
6. 计算本地contract state root。
7. 检查coinbase中的state root承诺。
8. 检查coinbase领取的gas费用。

任一检查不一致，区块无效。

## 测试网集成检查项

测试网启用合约前，节点配置必须至少确认：

1. 合约解析、区块验证和出块侧Result Builder全部开启，并使用相同网络参数和合约地址前缀。
2. coinbase必须写入统一contract state root，验证节点必须检查state root承诺。
3. EVM触发器扫描必须在每个候选区块运行，不能只在区块包含普通合约交易时运行。
4. Agent合约必须配置CoreNode地址、Agent收款地址、bootstrap收款地址和链参数。
5. Agent `ready`、`reject`和`confirm`必须由CoreNode地址发起，节点必须按最后输入前序输出地址验证CoreNode调用者身份。
6. caller/invoker身份解析必须依赖最后一个输入的前序输出地址，节点的UTXO视图必须能提供该前序输出脚本。
7. mempool必须拒绝外部提交的`CONTRACT_RESULT`，Result TX只允许由出块流程插入候选区块。
8. 本地测试必须覆盖deploy、invoke、result-only trigger、Agent ready/confirm、EVM state root、Template state root和混合区块state root。
9. 上线前需要固定gas参数、区块gas上限、合约Result打包费和触发器打包费；默认单次deploy/invoke gas上限为`50,000,000`，默认单次触发器gas上限为`5,000,000`，默认单区块EVM gas上限为`1,000,000,000`。
10. 节点、钱包、区块浏览器、资产浏览器和市场必须使用同一套合约交易解析和状态查询字段。

## 钱包、浏览器和市场接口契约

钱包、区块浏览器、资产浏览器和市场集成合约功能时，至少需要共享以下接口语义：

1. 合约部署接口：返回deploy txid、合约类型、合约地址、deployer、payload hash、初始状态和同区块Result状态。
2. 合约调用接口：构造`CONTRACT_INVOKE`，必须包含转入合约地址的gas/funding输出，并展示由最后输入前序输出解析得到的caller/invoker。
3. 合约结果查询接口：按txid、contract address、call id或trigger id查询canonical Result TX、状态、资产转移、gas费用和错误信息。
4. 合约状态查询接口：按合约地址查询合约类型、当前状态、state root、最近更新时间、余额和类型特有状态。
5. EVM接口：提供EVM地址和聪网合约地址互转、ABI calldata构造、event/log查询、EVM storage/code hash查询、触发器查询、compiler config和源码metadata查询。
6. Agent接口：提供预测合约deploy/ready/bet/confirm状态、投注聚合、候选结果、确认材料、CoreNode调用者身份和结算/退款结果查询。
7. 资产接口：按合约地址查询全部UTXO资产余额，并区分合约资金池、gas/funding输入、Result输出和找零输出。
8. 市场接口：市场只展示已经进入`Ready`或类型定义可公开展示状态的合约；涉及投注、购买或资产转移时，必须从节点查询最新状态和余额后构造交易。

这些接口返回的交易、状态和资产结果必须能追溯到链上交易、canonical Result TX和区块state root，不能只依赖前端本地推断。

## 索引器落库和查询要求

索引器必须为合约功能建立可查询的链上视图。索引器只消费已确认区块、canonical Result TX、已提交的contract index event和已提交的contract post-state projection；索引器不得执行template、EVM或Agent runtime，也不得自行生成合约历史。

索引器至少应建立以下统一视图：

1. 合约部署表：contract address、contract type、deploy txid、deployer、payload、payload hash、创建高度、创建时间和初始Result状态。
2. 合约调用表：invoke txid、contract address、caller/invoker地址、action、payload、gas/funding输出、确认高度和执行状态。
3. 合约Result表：result txid、contract address、result type、call id、trigger id、输入UTXO、输出资产转移、gas费用、执行状态、错误信息、高度和时间。
4. 合约状态表：contract address、contract type、state root、当前状态、类型特有状态、更新时间和最后Result txid；状态来源必须是已提交post-state projection。
5. EVM扩展表：EVM地址映射、code hash、storage root、logs/events、registered triggers和trigger执行历史。
6. Agent扩展表：Agent合约内容hash、ready结果、bet记录、outcome聚合、confirm记录、CoreNode调用者身份、确认结果文本、结果URL和结算/退款明细。
7. 资产视图：合约地址UTXO资产余额、已锁定资金池、Result转出、找零和费用归集。
8. 重组处理：索引器必须能按区块高度回滚合约部署、调用、Result、状态、触发器和资产视图。

查询API至少应支持按合约地址、txid、调用者地址、合约类型、状态、高度范围、trigger id、Agent outcome和EVM event topic检索。

## Mempool规则

mempool只做结构、地址、费用和基础协议检查。具体合约业务动作无效时，不应因为业务语义失败而阻塞mempool或出块；执行层应按合约规则将该调用处理为no-op或生成确定性的退款Result。`CONTRACT_RESULT`例外：Result TX由节点自动生成，不能忽略错误，验证不一致时区块无效。

mempool必须拒绝以下交易：

1. payload格式非法的`CONTRACT_DEPLOY`或`CONTRACT_INVOKE`。
2. 没有输出到合约地址的显式`CONTRACT_INVOKE`。
3. 输出到不存在合约地址的合约调用。
4. 显式`CONTRACT_INVOKE`没有且仅有一个输出到被调用合约地址。
5. gas limit缺失或超过协议上限。
6. gas/funding不足。
7. gas资产类型不符合协议规定。
8. 除部署分片外，OP\_RETURN数量超过当前策略上限。
9. 外部提交的`CONTRACT_RESULT`。


# 模板合约

模版合约是聪网原生智能合约类型。其执行逻辑由聪网节点源码中内置的Go runtime实现。

模版合约遵循[智能合约](https://github.com/sat20-labs/docs/tree/main/protocol/contracts/README.md)的通用协议。本文只定义模版合约特有规则。

## 合约类型

模版合约类型为：

```
ContractTypeTemplate
```

模版合约不执行EVM bytecode，不使用Solidity ABI，不维护EVM account state。模版合约也不是通道合约，不依赖RSMC通道、多方签名或承诺交易。

模版合约的资产控制边界来自合约VM状态和canonical `CONTRACT_RESULT`。

## 地址规则

模版合约使用通用合约地址格式：

```
ca/tc + version + ContractTypeTemplate + hash
```

模版合约地址hash长度为32字节。hash输入为：

1. `Contract.Encode()`得到的合约内容。
2. deployer。
3. 部署随机值。

部署随机值用于让相同deployer和相同合约内容生成不同合约地址。

模版合约runtime中的`URL()`等于合约地址。

## 部署规则

`CONTRACT_DEPLOY`用于部署模版合约。

部署payload包含：

1. 模版名称。
2. 模版版本。
3. deployer。
4. 部署随机值。
5. gas limit。
6. `Contract.Encode()`得到的合约内容。

节点根据部署payload生成合约地址、初始化runtime状态，并在同一区块内通过`CONTRACT_RESULT`记录部署结果和state root。

如果合约地址已存在，部署无效。

## 调用规则

`CONTRACT_INVOKE`用于调用模版合约。

调用交易必须输出到被调用合约地址。该输出同时作为：

1. Call TX和Result TX的绑定UTXO。
2. 本次调用转入合约的资产。
3. 本次调用和后续结算的费用来源。

调用者身份由调用交易最后一个输入解析得到。runtime中的用户状态、LP归属、refund权限和历史记录都使用该身份。

模版合约可以定义默认调用。默认调用由没有合约OP\_RETURN、但输出到模版合约地址的交易触发。合约根据输出中的资产类型和数量自行解释业务含义；如果该输出不符合合约可执行条件，合约可以将其视为无效业务输入而不改变业务状态。

## 费用规则

模版合约使用统一gas资产支付费用。

不同模版可以定义自己的调用费和撮合费。限价单和AMM模版沿用原通道合约的费用计算方式，但费用资产使用统一gas资产。

gas/funding输出中用于费用的部分不进入合约资产池。扣除费用后的剩余资产才作为合约可支配资产。

## Result TX规则

模版合约不接受外部提交的`CONTRACT_RESULT`进入mempool。

出块节点根据模版runtime结果构造canonical `CONTRACT_RESULT`。验证节点必须独立重放runtime，并比较区块中的Result TX。

如果Result TX缺失、输入输出不符合canonical规则，或与本地重放结果不一致，区块无效。

## 状态规则

模版合约状态属于全局合约VM状态。

模版合约state root、EVM合约state root和Agent合约state root合成统一的contract state root，并写入coinbase。

模版runtime必须满足：

1. 相同链上输入得到相同状态。
2. 不依赖本地时间、外部服务、随机数或其他非确定性数据。
3. 合约资产余额由合约地址UTXO集合和runtime状态共同验证。

## 第一阶段模版

第一阶段实现四类模版：

1. 限价单交易合约。
2. AMM交易合约。
3. 资产兑换合约。
4. 自动支付合约。

限价单和AMM模版从原通道合约业务逻辑迁移，但不保留以下能力：

1. 通道两端签名。
2. RSMC通道状态。
3. L1 deposit/withdraw。
4. L1 commit/reveal和BRC20 transfer inscription流程。
5. 老通道合约状态迁移。

自动支付合约不来自通道合约迁移，而是第一阶段新增的协议内置模版，用于把多个委托人的持续支付资金聚合在同一个合约中，并在每个区块生成一笔统一支付。

## 限价单交易合约

限价单交易合约对应原`SwapContractRuntime`的限价单交易逻辑。

接口名称和订单类型值与通道合约保持一致：

1. `swap`：挂买单或卖单。
2. `refund`：取消挂单或取回可退资产。
3. 买单订单类型为`2`。
4. 卖单订单类型为`1`。
5. refund订单类型为`3`。

撮合规则：

1. 买单按价格从高到低排序。
2. 卖单按价格从低到高排序。
3. 同价格按区块顺序、交易顺序和item id排序。
4. 只有买价大于或等于卖价时成交。
5. 成交价使用卖单价格。
6. 买单可以吃到更低价格卖单。
7. 每次撮合生成买家资产转移和卖家聪转移，两笔transfer位于同一个Result TX中。
8. 买单完成后，未使用的聪退回买家。
9. 卖单剩余资产不足以按价格成交时，剩余资产退回卖家。

refund规则：

1. `refund`参数包含item id列表。
2. item id列表为空时，取消调用者所有未完成挂单。
3. item id列表非空时，只取消指定item。
4. 调用者只能取消自己的挂单。
5. 已成交并已经通过Result TX发出的资产不再进入refund。

默认调用规则：

1. 向限价单合约输入聪时，合约按当前可成交的卖价解释为买入。
2. 向限价单合约输入该合约资产时，合约按当前可成交的买价解释为卖出。
3. 当前没有可参考成交价时，默认调用不产生新的订单或资产结算。

## AMM交易合约

AMM交易合约对应原AMM通道合约的swap和流动性逻辑。

接口名称和订单类型值与通道合约保持一致：

1. `swap`：AMM买入或卖出。
2. `refund`：取回可退资产。
3. `addliq`：添加流动性。
4. `removeliq`：移除流动性。
5. 买单订单类型为`2`。
6. 卖单订单类型为`1`。
7. 添加流动性订单类型为`9`。
8. 移除流动性订单类型为`10`。

部署和ready规则：

1. AMM合约部署内容包含资产名称、初始资产数量、初始聪数量和常数K。
2. 合约部署后，如果合约地址中的资产池、聪池或`asset*sats`没有达到部署参数要求，合约不进入可交易状态。
3. 合约可以通过`addliq`补充底池。
4. 当资产池、聪池和`asset*sats >= K`都满足后，合约进入可交易状态。
5. 合约ready后，正常交易过程中不再要求实时`asset*sats >= K`。
6. 如果池子被移空，合约退出可交易状态，必须再次通过`addliq`达到初始K后才能重新ready。

AMM swap规则：

1. AMM采用常数乘积公式。
2. AMM买入时，用户输入聪，输出资产。
3. AMM卖出时，用户输入资产，输出聪。
4. AMM卖出参数中的`Amt`表示最小可接受输出聪数量，输入资产数量以Call TX funding output为准。
5. AMM买入参数中的`Amt`表示最小可接受输出资产数量，输入聪数量以Call TX funding output为准；`UnitPrice`只能作为报价或滑点约束，不能作为输入金额的第二来源。
6. 滑点保护失败时，本区块直接生成refund result。
7. 同一区块内多笔swap按canonical交易顺序逐笔处理。每笔成交使用上一笔成交后更新的池子和K定价；输入资产扣除0.8%服务费后参与常数乘积计算，但池子余额加入完整输入，使服务费留在池中。买入参数`Amt`只表示最小可接受输出，满足滑点条件后整笔输入参与兑换，不按`Amt`截断成交或退回多余输入。
8. 同一区块内AMM先处理swap，再处理add/remove liquidity，以对齐原通道合约。
9. 因addliq达到ready的区块不会同时撮合之前等待中的swap，等待中的swap会在后续区块结算。

AMM默认调用规则：

1. 向AMM合约输入聪时，合约解释为买入。
2. 向AMM合约输入该合约资产时，合约解释为卖出。
3. 不符合AMM交易语义的默认调用不改变AMM业务状态。

流动性规则：

1. `addliq`调用的入池资产数量和入池聪数量以Call TX funding output为准。
2. `addliq`参数只应表达最小可接受LPT、比例约束、deadline等不能由funding output推导的约束，不应重复表达入池资产数量或入池聪数量。
3. 多余资产或多余聪按池子比例计算后通过Result TX退回。
4. `removeliq`参数包含要移除的LPT数量。
5. 如果请求移除的LPT超过调用者余额，按调用者实际LPT余额处理。
6. 移除流动性时，LP获得对应池子份额。
7. 产生利润时，LP获得60%利润；原服务端和基金会两部分合并后统一给基金会。
8. 当前实现使用部署者地址作为基金会接收地址。

## 资产兑换合约

资产兑换合约用于按部署者设定的规则出售库存资产A。invoker输入资产B后获得资产A，deployer在同一个canonical `CONTRACT_RESULT`中获得成交消耗的资产B。

部署内容包含：

1. 资产A名称。
2. 资产B名称。
3. 价格模式。
4. 价格阶梯表。

价格模式支持：

1. `height`：按区块高度选择当前价格阶梯。
2. `sold_a`：按累计已售出资产A数量选择当前价格阶梯。

价格阶梯表中的`bPerA`表示兑换1单位资产A需要支付的资产B数量。第一档阈值必须为0，后续阈值必须严格递增。

接口规则：

1. `exchange`：输入资产B并兑换资产A，参数可以包含最小可接受输出资产A数量。
2. `close`：仅deployer可调用，关闭合约并取回剩余资产A。
3. 无参数默认调用输入资产A时，视为补充库存。
4. 无参数默认调用输入资产B时，视为按当前价格兑换资产A。
5. 无参数默认调用同时输入资产A和资产B时，资产A先补充库存，资产B再用于兑换。

兑换规则：

1. 成交价由部署时的价格模式和当前区块状态确定。
2. 合约最多输出当前可用库存资产A。
3. 输入资产B数量以Call TX funding output为准；当库存资产A不足以满足输入资产B时，按当前价格部分成交，未使用的资产B退回invoker。
4. 当`exchange`参数中的最小输出资产A不满足时，净输入资产B退回invoker。
5. 合约关闭后不再接受新的兑换，后续兑换输入按失败处理。

gas同名规则：

1. 资产A或资产B都可以与统一gas资产同名。
2. 当gas资产等于资产A时，先从可用资产A中扣除本次Result费用，剩余资产A才可作为库存或兑换输出。
3. 当gas资产等于资产B时，先从本次输入资产B中扣除本次Result费用，剩余资产B才参与兑换。
4. 当gas资产不同于资产A和资产B时，gas按模版合约通用费用规则处理。

## 自动支付合约

自动支付合约用于把多个地址委托的持续支付资金聚合到同一个合约中，并按区块向一个接收地址或当前出块矿工支付费用。模版名称为：

```
autopay.tc
```

部署内容包含：

1. 服务名称。
2. 接收地址；为空时表示每个区块的支付作为矿工费用支付给当前出块矿工。
3. 支付资产名称，可以是聪或任意聪网资产。
4. 个人每区块最低支付额度。

部署内容不包含用户列表、支付区间、支付结束高度或按高度变化的曲线。每个委托人自己的支付额度和余额由后续调用写入runtime state。

调用接口：

1. `config`：委托人设置自己的每区块支付额度，额度不得低于合约最低额度。
2. `default invoke`：委托人向合约地址funding，增加自己的可支付余额；如果委托人没有配置额度，默认使用合约最低额度。
3. `cancel`：委托人取消自己的支付配置，并退回该委托人的剩余支付余额。
4. `close`：只有deployer可以关闭合约，并批量退回所有委托人的剩余支付余额。

支付资产可以是聪或任意聪网资产。如果支付资产本身就是gas资产，runtime需要在同一种物理资产中区分业务支付余额和合约trigger/result gas余额。

委托状态：

1. runtime为每个委托地址维护独立状态，包括每区块支付额度、funding余额、累计已支付额度、已支付区块数量、最近支付高度和委托状态。
2. 委托状态可以是active、funding或closed。
3. 合约总的可支付余额是所有委托人余额之和。
4. 合约状态可以对外返回聚合余额，也可以返回每个委托人的可审计状态。

激活和funding规则：

1. 部署交易或默认调用都可以向合约地址funding。
2. 部署交易的funding归属于deployer。
3. 默认调用的funding归属于该调用的invoker。
4. 当至少一个委托人余额足够支付其下一块费用，并且合约有足够trigger/result gas时，合约处于active状态。
5. 某个委托人余额不足支付一个区块时，该委托人进入funding状态，不参与该区块支付；其他余额充足的委托人仍可继续支付。
6. 如果所有委托人都无法支付，或合约缺少必要trigger/result gas，合约整体进入funding状态，等待后续funding。

支付规则：

1. 每个区块结算时，runtime扫描所有active委托人。
2. 对每个余额足够的委托人，扣除其每区块支付额度。
3. 出块节点自动生成一笔canonical `CONTRACT_RESULT`，把本区块所有委托人的应付金额合并为一个支付输出。
4. 如果接收地址不为空，支付输出转给该接收地址。
5. 如果接收地址为空，支付输出作为矿工费用进入本区块收益。
6. 一个区块只应为该自动支付合约生成一笔支付Result，避免大量委托人导致区块中出现过多自动trigger交易。

关闭规则：

1. 只有deployer可以关闭自动支付合约。
2. close时，合约按委托人分别退回各自剩余支付余额。
3. 每笔close Result最多包含1000个退款输出；如果委托人数量超过单笔上限，未退回的余额保留在合约地址，并在后续Result中继续处理。
4. close完成后，合约管理的剩余gas余额退回deployer。
5. 合约地址上不属于合约管理余额的其他资产，继续按通用合约framework的剩余资产处理规则执行。


# 自然语言合约

自然语言合约是由AI Agent支持的聪网智能合约类型。合约内容以自然语言协议表达，由AI Agent进行结构化解释、验证和执行建议生成。

自然语言合约遵循[智能合约](https://github.com/sat20-labs/docs/tree/main/protocol/contracts/README.md)的通用协议。本文只定义自然语言合约的边界和第一阶段要求。

## 命名

建议命名：

1. 中文名：自然语言合约。
2. 英文名：Natural Language Contract。
3. 技术简称：Agent合约。
4. 代码类型：`ContractTypeAgent`。

协议文档中使用“自然语言合约”。代码类型和内部实现可以使用`Agent`。

## 合约类型

自然语言合约类型为：

```
ContractTypeAgent
```

自然语言合约不是EVM合约，不要求用户编写Solidity、ABI或bytecode。

自然语言合约不是模版合约，不要求合约逻辑预先固化在聪网节点源码中。

自然语言合约不是通道合约，不依赖RSMC通道、多方签名或承诺交易。

## CoreNode Agent

聪网自然语言合约由协议内置的AI Agent支持。第一阶段可以将整个聪网网络理解为只有一个协议Agent，该Agent由内置CoreNode执行。

CoreNode身份由协议配置中的CoreNode地址确定。节点验证`ready`、`reject`和`confirm`等CoreNode专用接口时，按通用caller规则解析调用交易最后一个输入的前序输出地址，并要求该地址等于协议配置的CoreNode地址。

CoreNode确认结果本身不再在payload中重复携带CoreNode公钥和签名。确认交易必须由有效CoreNode地址发起；Result TX和state root仍由所有节点独立验证。这样可以避免在payload中存储冗余身份字段，并让CoreNode身份检查与其他合约调用保持一致。

CoreNode在自然语言合约中同时承担以下角色：

1. Agent执行者。
2. 合约内容可理解性、可验证性和可执行性的审核者。
3. 协议oracle。
4. 生成自然语言合约执行结论的授权实体。

自然语言合约的普通用户不能替代CoreNode生成协议认可的Agent结论。普通用户可以部署合约、提交材料、请求执行或发起争议，但不能调用只允许CoreNode调用的内置Agent接口。

后续协议可以扩展为多Agent验证模式，例如3个Agent中至少2个给出一致结论才接受执行结果。测试阶段可以先采用单CoreNode Agent模式。

## 合约内容

自然语言合约内容是一份可执行协议文本。协议文本必须能被AI Agent解析为可验证、可验收、可执行的结构。

协议文本应包含：

1. 合同目的。
2. 参与方和角色。
3. 标的资产。
4. 资产进入合约的方式。
5. 触发条件。
6. 验证数据来源。
7. 验收标准。
8. 执行方式。
9. 超时、失败和争议处理。
10. 可生成的资产转移结果。

合约可以包含结构化辅助字段：

1. 资产列表。
2. 参与方地址列表。
3. 时间或区块高度限制。
4. 允许使用的数据源。
5. 验证器或仲裁器规则。
6. 合约版本。

自然语言正文是合约语义的核心来源。结构化字段只能辅助解析，不得改变正文的核心含义。

## 部署规则

`CONTRACT_DEPLOY`用于部署自然语言合约。

部署payload包含：

1. 合约类型。
2. 合约正文。
3. 合约版本。
4. deployer。
5. 部署随机值。
6. 可选结构化辅助字段。

自然语言合约部署后不会自动进入可执行状态。部署成功只创建一个待确认合约，初始状态为`PendingReady`。

所有自然语言合约都必须提供一个固定的CoreNode激活接口：

```
ready
```

`ready`接口只能由CoreNode调用，其他地址无权调用。调用者身份仍按通用规则由调用交易最后一个输入解析得到。

CoreNode调用`ready`接口时，需要检查：

1. 内容是否完整。
2. 条件是否可验证。
3. 验收标准是否明确。
4. 执行结果是否可以映射为Asset Intent。
5. 是否依赖不可验证或不可共识的私有事实。
6. 是否存在矛盾条款、循环条件或无法执行的条款。

如果检查通过，CoreNode交互生成canonical `CONTRACT_RESULT`，该Result声明合约进入`Ready`状态。只有进入`Ready`状态的自然语言合约才能接受普通业务调用。

如果检查不通过，CoreNode交互生成拒绝结果，合约进入`Rejected`或`Invalid`状态。未进入`Ready`状态的合约不得产生资产转移执行结果。

## 调用规则

`CONTRACT_INVOKE`用于向自然语言合约提交事件、证明、验收请求、执行请求或争议材料。

调用内容可以包含：

1. 触发动作。
2. 调用者身份。
3. 链上证明。
4. 外部证明。
5. 验收材料。
6. 执行请求。
7. 争议或申诉材料。

调用交易必须输出到被调用合约地址，作为gas/funding输出。调用者身份由调用交易最后一个输入解析得到。

自然语言合约默认调用不携带自然语言材料或结构化动作。第一阶段可作为向合约地址转入资产的普通链上行为，除非合约协议明确规定默认行为，否则不改变自然语言合约业务状态。

自然语言合约调用分为两类：

1. CoreNode内置调用：包括`ready`以及后续协议定义的Agent专用接口，只允许CoreNode调用。
2. 普通业务调用：由参与方或其他授权地址提交事件、证明、验收、执行请求或争议材料。

除`ready`外，普通业务调用只能在合约状态为`Ready`后生效。

## AI Agent执行规则

AI Agent根据合约正文、合约状态、触发条件、证明材料和链上环境生成结构化执行结论。

第一阶段Agent由CoreNode执行。CoreNode生成的Agent结论进入聪网合约执行流程，并通过canonical `CONTRACT_RESULT`表达。Agent不能只输出自由文本，必须输出可验证、可比较、可重放的结构化结论。

执行结论必须包含：

1. 触发条件是否满足。
2. 使用的验证材料。
3. 验收是否通过。
4. 需要生成的Asset Intent。
5. 是否需要等待更多材料。
6. 是否进入失败、超时或争议状态。
7. 结论摘要。

AI Agent不能直接花费UTXO。资产转移必须通过canonical `CONTRACT_RESULT`结算。

Agent具体执行方式仍需后续明确，至少包括：

1. 模型版本或Agent实现版本。
2. 固定提示词和解释规则。
3. 结构化输出schema。
4. 输出签名或CoreNode身份验证方式。
5. 单Agent模式和多Agent阈值模式的切换规则。
6. 失败、超时、争议和重试规则。

## 可验证性

自然语言合约必须避免依赖无法形成共识的事实。

允许的数据来源包括：

1. 聪网链上交易。
2. 合约自身状态。
3. 指定链上合约或预言机结果。
4. 部署时指定的外部证明。
5. 多方签署的验收材料。
6. 协议允许的AI Agent验证结果。
7. CoreNode作为协议oracle给出的验证结果。

如果多个节点的AI Agent可能对同一材料得出不同结论，协议必须提供约束机制：

1. 固定模型版本。
2. 固定提示词和解释规则。
3. 固定结构化输出格式。
4. 多Agent共识。
5. 仲裁器或挑战期。
6. 只接受可独立校验的证明材料。

## Result TX和状态

自然语言合约不接受外部提交的`CONTRACT_RESULT`进入mempool。

出块节点根据AI Agent执行结论构造canonical `CONTRACT_RESULT`。验证节点必须根据协议规定的Agent验证方式复核执行结论，并比较Result TX。

自然语言合约结果进入聪网合约结果流程。无论是`ready`激活结果、拒绝结果、普通执行结果、失败结果还是争议结果，都必须通过canonical `CONTRACT_RESULT`表达，不能由外部用户直接提交非canonical Result TX。

自然语言合约状态至少包含：

1. 合约正文hash。
2. 合约版本。
3. 当前执行状态。
4. 已提交证明。
5. 已验收事项。
6. 待执行事项。
7. 已生成结果。
8. 争议或失败状态。

自然语言合约状态应尽量使用统一状态定义。不同合约可以只使用其中一部分状态，但相同状态名称在不同自然语言合约中必须表达相同含义。

基础状态包括：

1. `PendingReady`：合约已部署，等待CoreNode调用`ready`审核。
2. `Ready`：CoreNode已确认合约内容可理解、可验证、可执行，可以接受普通业务调用。
3. `Rejected`：CoreNode拒绝激活，合约不能执行普通业务调用。
4. `Invalid`：合约内容、结构或调用材料无效，不能进入后续执行流程。
5. `PendingEvidence`：合约等待参与方提交证明或验收材料。
6. `PendingExecution`：触发条件已满足，等待Agent生成执行结论或等待Result结算。
7. `Completed`：合约主要义务已完成，相关资产转移已经结算。
8. `Failed`：合约因失败条件、超时或不可执行原因结束。
9. `Disputed`：合约进入争议状态，等待CoreNode、仲裁器或协议定义的争议流程处理。
10. `Expired`：合约超过有效期且未满足继续执行条件。

Agent合约state root必须进入统一contract state root。

## 预测型自然语言合约

\[仅用于测试网络演示]

第一阶段优先支持预测型自然语言合约。预测型自然语言合约是`ContractTypeAgent`下的固定子类型：

```
prediction
```

预测型自然语言合约当前仅在testnet启用。mainnet下Agent合约暂不开放可用子类型，节点、oracle、索引器和市场都不应把prediction作为mainnet可用合约展示或执行。

预测型自然语言合约用于表达一个可验证事件的多个候选结果。用户向合约地址投注，Agent在事件结束后根据部署时指定的数据来源确认最终结果，合约根据确认结果自动分配奖金或退款。

预测型自然语言合约的Agent只负责：

1. `ready`：审核合约内容是否可以被理解、验证和执行。
2. `confirm`：根据指定数据来源提交最终结果。

下注记录、手续费、奖金分配、退款和合约关闭都由预测合约runtime确定性处理。

### 部署payload

预测型自然语言合约的部署payload包含：

```json
{
  "subtype": "prediction",
  "title": "...",
  "description": "...",
  "time_base": "unix",
  "event_time": 1780310400,
  "bet_deadline": 1780306800,
  "confirm_after": 1780396800,
  "source_url": "https://xxx.com",
  "bet_asset": "::",
  "min_bet_unit": "10000",
  "outcomes": [
    {"id": "a", "text": "..."},
    {"id": "b", "text": "..."},
    {"id": "c", "text": "..."}
  ]
}
```

字段规则：

1. `subtype`必须为`prediction`。
2. `title`和`description`描述预测目标。
3. `time_base`指定时间基准，可以为`unix`或`height`。
4. `event_time`、`bet_deadline`和`confirm_after`按`time_base`解释。
5. `source_url`为部署时指定的数据来源站点或入口URL，可以是比赛预告页面、赛事页面或结果查询网站。
6. `bet_asset`为投注资产名称，使用聪网资产层的`AssetName.String()`格式。
7. `min_bet_unit`为最小投注份额，使用字符串表达，最终按`bet_asset`对应资产属性解析为Decimal。
8. `outcomes`为候选结果列表，数量不固定，但至少包含2个候选结果。
9. `outcomes.id`使用小写字母编号，例如`a`、`b`、`c`，同一个合约内必须唯一。
10. 部署payload不包含手续费比例、Agent策略、bootstrap地址或Agent地址，这些属于协议内置配置。

### 内置配置

预测型自然语言合约第一阶段使用协议内置配置：

1. 部署者手续费：奖池的6%。
2. Agent手续费：奖池的3%。
3. bootstrap node手续费：奖池的1%。
4. 赢家奖池：奖池的90%。

如果后续采用3个Agent的多Agent模式，Agent手续费总额仍为3%，每个参与并形成有效确认结果的Agent获得1%。当前单Agent模式下，CoreNode Agent获得完整3%。

bootstrap node收款地址由协议内置bootstrap公钥推导，当前参考实现可使用`indexer/common/btc.go`中的`GetBootstrapAddress()`。Agent收款地址由协议内置Agent/CoreNode公钥推导，后续实现可以增加与`GetBootstrapAddress()`对应的Agent地址推导函数。

### 下注规则

预测型自然语言合约进入`Ready`状态后，内部状态进入`Betting`，用户可以通过`bet`调用参与投注。

`bet`调用参数包含：

```json
{
  "outcome_id": "a"
}
```

下注规则：

1. 任何地址都可以调用`bet`。
2. 合约必须处于通用`Ready`状态，且预测合约内部状态必须为`Betting`。
3. 当前时间或区块高度必须小于或等于`bet_deadline`。
4. `outcome_id`必须存在于部署payload的`outcomes`列表中。
5. 下注资产必须为部署payload中的`bet_asset`。
6. 下注金额以Call TX转入合约地址的funding output为准，不能以调用参数中的金额为准。
7. 下注金额必须大于或等于`min_bet_unit`。
8. 下注金额必须是`min_bet_unit`的整数倍。
9. 同一地址可以对多个候选结果下注。
10. 同一地址对同一候选结果多次下注时，状态按地址和候选结果聚合金额，历史记录保留每次调用。

每个候选结果的投注都必须独立满足最小投注份额和整数倍规则。

### 结果确认

`confirm`是预测型自然语言合约的Agent结果确认接口，只允许CoreNode Agent调用。第一阶段默认触发器为`confirm`调用。

`confirm`调用参数包含：

```json
{
  "result_type": "outcome",
  "outcome_id": "a",
  "result_url": "https://xxx.com/match/result/123",
  "result": "Team A 2-1 Team B",
  "observed_at": 1780314000,
  "agent_version": 1,
  "model_version": "model-v1"
}
```

确认规则：

1. 调用者必须是CoreNode Agent。
2. 合约必须已经进入`Ready`状态。
3. 当前时间或区块高度必须已经超过`bet_deadline`。
4. 当前时间或区块高度必须已经到达`confirm_after`。
5. `result_type`必须为`outcome`、`cancelled`、`invalid`或`unverifiable`之一。
6. 当`result_type`为`outcome`时，`outcome_id`必须存在于部署payload的`outcomes`列表中。
7. 当`result_type`为`cancelled`、`invalid`或`unverifiable`时，`outcome_id`可以为空，合约进入全额退款流程。
8. `result_url`为Agent实际用于确认结果的具体页面URL，可以不同于部署payload中的`source_url`。
9. `result_url`必须属于部署payload中`source_url`指定的网站范围：scheme必须相同，hostname必须相同或为其子域名；如果发生HTTP跳转，跳转后的最终URL也必须满足同样规则。
10. `result`记录Agent观察到的实际结果，例如比分、取消说明或不可验证说明；长度上限为128字节。
11. `observed_at`记录Agent观察到结果的时间或高度。
12. `agent_version`为整数版本号，记录生成确认结果的Agent实现版本。
13. `model_version`记录生成确认结果的模型版本。

Agent根据部署payload中的`source_url`确定允许的数据来源范围，并在该网站范围内找到具体结果页面`result_url`。Agent解析`result_url`内容，找到预测事件的最终结果，然后通过`confirm`提交结构化结果。合约runtime只处理结构化结果，不直接依赖非结构化网页内容进行资金分配。

清洗后文本应去除脚本、样式、广告、导航和明显动态噪声，只保留Agent用于判断结果的主体文本。第一阶段共识节点验证CoreNode调用者身份和结构化确认结果，不在区块验证路径重新抓取网页。索引器、浏览器和审计工具可以通过`result_url`、`result`、`observed_at`和Agent日志复核CoreNode确认过程。

如果采用多Agent模式，多个Agent分别提交`confirm`结果。合约runtime在相同`result_type`和相同`outcome_id`达到协议阈值后确认最终结果，并按该结果自动结算或退款。

### 自动结算和退款

预测型自然语言合约不提供对外开放的`settle`或`refund`接口。正常情况下，`confirm`触发合约自动结算或退款。

有赢家时，合约按以下顺序分配runtime记录的有效投注`bet_asset`资金：

1. 6%发送给deployer。
2. 3%发送给Agent。
3. 1%发送给bootstrap node。
4. 剩余90%按赢家下注金额占全部赢家下注金额的比例分配给赢家。

手续费和赢家分配使用Decimal计算。比例计算产生的余数进入赢家奖池。赢家分配产生的余数按赢家下注金额从大到小分配；下注金额相同时，按地址字典序分配。

没有赢家时，合约不收取手续费，runtime记录的有效投注`bet_asset`资金按原下注金额比例退款。

以下情况进入全额退款流程，不收取手续费：

1. 比赛或事件取消。
2. 数据来源可访问但结果不在候选结果列表中。
3. Agent确认结果为不可验证或无效。
4. 合约内容在ready后发现无法执行且尚未完成结算。

`confirm_after`是Agent开始检查结果的预期时间或高度。到达`confirm_after`后，Agent开始检查数据来源并尝试确认结果；如果Agent尚未确认，合约不自动退款，继续等待Agent处理。

只有通过有效`bet`调用并被runtime记录的`bet_asset`资金参与当前预测合约结算。无效调用、非投注资产和合约地址上超出runtime记录的资产按通用framework规则处理，不参与预测奖金分配。

### 部署者提前关闭边界

预测型自然语言合约允许deployer在`bet_deadline`结束前调用`close`提前关闭市场。关闭时，runtime记录的全部有效投注按原投注金额全额退款，不收取手续费。

关闭规则：

1. 调用者必须是deployer。
2. 当前时间或区块高度必须小于或等于`bet_deadline`。
3. 当前时间或区块高度超过`bet_deadline`后，deployer不再允许调用`close`。
4. 合约处于`ClosedForBet`或`PendingResult`时，结果确认权属于Agent，deployer不能替代Agent判断事件结果。
5. 比赛取消、结果无效、数据不可验证或合约无法执行时，应由CoreNode Agent通过`confirm`提交`cancelled`、`invalid`或`unverifiable`结果，并触发全额退款。
6. 到达`confirm_after`后Agent尚未确认时，协议选择继续等待Agent处理，不授权deployer绕过Agent触发退款。

### 内部状态

预测型自然语言合约使用通用`Ready`状态表示合约已经通过CoreNode审核，可以接受业务调用。预测业务自身维护独立内部状态：

1. `Betting`：允许用户下注。
2. `ClosedForBet`：下注截止，不再接受新下注。
3. `PendingResult`：等待Agent提交最终结果。
4. `Confirmed`：结果已经被Agent确认或达到多Agent阈值。
5. `Settled`：奖金已经分配，合约关闭。
6. `Refundable`：合约进入退款流程。

`Betting`不是通用合约状态，只是预测型自然语言合约的内部状态。

## 第一阶段定位

自然语言合约第一阶段允许先以单CoreNode Agent模式进入聪网合约结果流程。合约部署后必须先由CoreNode通过`ready`接口确认，确认结果通过canonical `CONTRACT_RESULT`写入链上状态。

第一阶段仍需继续明确Agent执行细节。进入完整主网共识执行前，必须明确模型确定性、验证方式、挑战机制、仲裁机制、多Agent阈值规则和state root承诺规则。


# EVM 合约

EVM合约是聪网智能合约的一种执行类型。EVM执行Solidity/EVM状态机，聪网UTXO模型负责真实资产来源和资产结算。

EVM合约遵循[智能合约](/xie-yi-yu-an-quan/smart-contracts/contracts)的通用协议。本文只定义EVM合约特有规则。

## 合约类型

EVM合约类型为：

```
ContractTypeEVM
```

EVM合约兼容EVM执行语义、ABI、Solidity开发模型和EVM事件模型，但不采用以太坊账户资产模型。EVM合约内部状态可以维护应用账本，真实资产余额以合约地址UTXO集合为准。

## 地址规则

EVM内部地址保持20字节，以兼容Solidity和ABI。

1. `msg.sender`是20字节EVM地址。
2. `address(this)`是20字节EVM合约地址。
3. event topic中的indexed address按EVM ABI编码。
4. CREATE和CREATE2生成20字节EVM合约地址。

聪网外部合约地址使用：

```
ca/tc + version + ContractTypeEVM + hash
```

EVM合约地址hash为20字节EVM地址。EVM内部20字节地址和聪网外部`ca/tc`地址必须支持无损转换。

chain id、vm version和code hash不放入地址hash：

1. chain id由网络和地址前缀区分。
2. vm version由地址version、type和协议升级规则表达。
3. code hash由部署交易、合约状态和state root承诺表达。

## 部署规则

`CONTRACT_DEPLOY`用于部署EVM合约。

EVM部署payload包含：

1. init code。
2. constructor参数。
3. deployer EVM address。
4. gas limit。
5. 部署nonce。

部署成功后生成：

1. 20字节EVM合约地址。
2. 聪网`ca/tc`合约地址。
3. code hash。
4. 初始storage root。

部署结果必须通过同一区块内的canonical `CONTRACT_RESULT`记录。

## 调用规则

`CONTRACT_INVOKE`用于调用EVM合约。

EVM调用payload包含：

1. calldata。
2. gas limit。
3. call nonce。

调用交易必须输出到被调用合约地址，作为gas/funding输出。被调用合约地址由Call TX输出解析，不写入OP\_RETURN。

EVM `msg.sender`由调用交易最后一个输入的前序输出地址确定，再映射为20字节EVM地址。节点不得从witness公钥推导`msg.sender`。

EVM合约的默认调用表示向合约地址发起一次空calldata调用。输出中的satoshi作为`msg.value`，其他资产仍由聪网资产层和预编译资产接口表达。

EVM calldata直接作为EVM调用输入，不在协议层预定义业务action和参数。合约如果需要读取本次Call TX转入合约地址的资产数量，应通过预编译资产接口查询funding output，而不是要求用户在calldata中重复填写同一经济参数。

## StateDB和执行器

EVM执行器第一阶段基于go-ethereum `core/vm`。

实现要求：

1. 不修改EVM opcode语义。
2. 实现聪网自定义StateDB。
3. StateDB维护storage、code、log和state root。
4. 合约资产由UTXO集合表达，不由EVM account balance表达。

## 资产规则

资产名称在ABI中按字符串编码，使用聪网资产层`AssetName.String()`结果。

satoshi资产名称固定为：

```
::
```

第一阶段支持聪网已识别并能以UTXO表达的资产：

1. satoshi。
2. ORDX资产。
3. Runes资产。
4. BRC20资产。
5. 其他已被聪网资产层识别的资产。

EVM合约内部可以维护ERC20或其他应用层余额。该余额不等同于聪网原生资产余额。需要兑现为聪网资产转移时，合约必须通过资产接口生成Asset Intent，并由`CONTRACT_RESULT`结算。

## 预编译资产接口

EVM不能直接花费UTXO，只能生成Asset Intent。底层资产接口通过预编译合约提供。

预编译合约负责：

1. 查询合约UTXO资产状态。
2. 生成资产转移intent。
3. 参与Result TX确定性验证。

当前资产预编译地址为：

```
0x0000000000000000000000000000000000534E01
```

第一阶段接口：

1. `balanceOf(address owner, string assetName) returns (string)`：查询指定EVM地址对应合约地址当前可用的指定资产余额。
2. `fundingAssetAmount(string assetName) returns (string)`：查询本次Call TX funding output中指定资产的剩余可认领数量。若`assetName`为统一gas资产，返回值会扣除本次调用预留的Result费用后再提供给合约。
3. `fundingSats() returns (uint256)`：查询本次Call TX funding output中的白聪数量。
4. `claimFundingAsset(string assetName, string amount) returns (bool)`：合约明确认领本次funding中的指定资产数量。只有被认领的funding资产进入本次合约业务处理；未认领的多余资产按framework规则退款或保留为非业务资产。
5. `callerAddress() returns (string)`：返回按通用规则解析出的聪网caller地址。
6. `transferAsset(string assetName, string to, string amount, bytes extraData) returns (bool)`：声明一笔资产转移intent。
7. `transferAssets(string[] assetNames, string[] recipients, string[] amounts, bytes[] extraData) returns (bool)`：声明多笔资产转移intent。该接口用于close或批量结算时一次性表达多个接收者和多种资产。
8. `compareAmount(string left, string right) returns (int256)`：按Decimal语义比较两个资产数量字符串。
9. `addAmount`、`subAmount`、`mulAmount`、`divAmount`：按Decimal语义计算资产数量字符串。
10. `uintToAmount(uint256)`、`amountToUintFloor(string)`、`amountToUintCeil(string)`：在整数和资产数量字符串之间转换。

所有资产数量在预编译资产接口中优先使用字符串表达。EVM合约内部可以为了业务计算临时转换为`uint256`，但最终资产转移intent必须回到资产字符串，并由Result TX按资产精度截断或校验。

## `msg.value`和balance

`msg.value`表示本次Call TX转入合约地址的satoshi数量。

`address.balance`返回satoshi余额。`address(this).balance`表示当前合约地址可支配的satoshi总量，该数值由合约地址UTXO集合统计得到。

多资产余额必须通过预编译合约查询。合约storage中的资产记录如果与UTXO统计不一致，Result TX验证以UTXO资产状态和预编译接口为准。

## 合约信息和状态视图接口

为了让钱包、应用前端和浏览器在不知道具体Solidity源码的情况下展示基础信息，建议EVM合约实现一组轻量只读接口：

```solidity
function contractName() external view returns (string memory);
function contractSubtype() external view returns (string memory);
function managedAssetCount() external view returns (uint256);
function managedAsset(uint256 index) external view returns (string memory);
function managedAssetBalance(uint256 index) external view returns (string memory);
function managedAssetBalance(string calldata assetName) external view returns (string memory);
```

节点查询EVM合约状态时会尝试调用这些接口。没有实现`contractName()`的合约，基础显示名称返回`unknown`。`managedAsset*`接口用于返回合约自己认为正在管理的资产名称和数量；浏览器仍可以同时展示合约地址UTXO中的实际资产余额，两者不要求完全相等，但差异应被视为需要关注的合约状态信息。

合约可以额外实现：

```solidity
function stateView() external view returns (string memory);
```

`stateView()`返回合约自定义JSON字符串，用于展示订单簿、池子、用户份额或其他业务视图。该视图不替代共识状态，只是对合约storage和资产状态的可读投影。

## 部署工具和源码metadata

钱包可以提供Solidity源码编译入口。编译参数不由用户自由选择，而由聪网当前支持的EVM编译配置决定，并展示给用户。当前测试阶段默认配置为：

1. `solcVersion`: `0.8.30`。
2. `evmVersion`: `paris`。
3. optimizer开启，`runs=200`。
4. metadata `bytecodeHash=none`。
5. 只支持单文件源码，不允许import。

部署交易确认后，钱包或部署工具可以把合约地址、Solidity源码、ABI、compiler config、constructor参数和init/runtime code hash提交给L2 indexer的metadata接口。indexer保存metadata用于浏览器、应用前端和钱包展示；metadata不是共识状态，不能替代链上deploy交易、EVM code hash和state root。

## Gas

EVM保留gas机制。

规则：

1. opcode gas成本沿用geth。
2. 每个部署和调用必须声明gas limit。
3. 执行超过gas limit时结果为out of gas。
4. gas费用由调用方承担。
5. 区块存在EVM gas总上限。
6. gas price第一阶段采用协议固定值。
7. gas费用使用统一gas资产支付。
8. gas费用归出块节点。

默认gas上限参数：

1. 单次deploy/invoke gas上限为`50,000,000`。
2. 单次触发器执行gas上限为`5,000,000`。
3. 单区块EVM执行总gas上限为`1,000,000,000`。

## 触发器

EVM合约可以通过协议预编译合约注册高度触发器。触发器记录在EVM状态中，并参与EVM state root。

高度触发器至少包含：

1. trigger id。
2. 目标合约地址。
3. 触发高度。
4. 触发执行gas limit。
5. 触发时调用的calldata。

出块节点在构造每个区块时必须检查EVM状态中已经到期的触发器。即使候选区块没有普通EVM deploy/invoke交易，只要存在到期触发器，也必须执行触发器并在需要结算时生成canonical `CONTRACT_RESULT`。

验证节点遇到没有同区块EVM deploy/invoke的EVM Result TX时，必须通过Result TX花费的EVM合约UTXO确定合约地址，并基于上一EVM状态、当前区块高度和区块确认时间重放触发器。触发器不存在、未到期、已被移除、gas limit无效或重放结果不一致时，区块无效。

触发器注册和执行必须同时满足：

1. gas limit必须为正数。
2. gas limit不能超过单次触发器执行gas上限。
3. 合约必须有足够gas资金覆盖触发器执行和Result TX打包费用。
4. 区块内所有EVM执行的累计gas不能超过单区块EVM执行总gas上限。

## Result TX和state root

EVM合约不接受外部提交的`CONTRACT_RESULT`进入mempool。

出块节点执行EVM后，根据Asset Intent构造canonical `CONTRACT_RESULT`。验证节点独立重放EVM，并比较Result TX和state root。

EVM state root、模版合约state root和Agent合约state root合成统一contract state root，写入coinbase。

## 关闭规则

EVM合约使用通用`close`语义。deployer发起合约关闭时，EVM执行器会先尝试调用合约的：

```solidity
function close() external returns (bool);
```

合约应在`close()`中通过预编译资产接口为自己管理的资产生成必要的转移intent，例如返还LP、订单、押金或其他有明确归属的资产。`close()`执行完成后，framework再按通用规则处理合约管理资产中的剩余利润，以及合约地址上超出runtime管理记录的非管理资产。

如果EVM合约没有实现`close()`或`close()`失败，节点仍会按协议规则处理Result验证；但作为可公开使用的合约，应实现明确的`close()`，并使用`transferAssets`一次性表达多资产、多接收者的关闭分配。


# Security


# 威胁模型与信任假设

聪网安全不是一个余额数字，而是一组可以验证的退出证据和信任边界。

## 核心信任假设

1. Bitcoin L1 提供最终结算和争议边界。
2. Indexer 需要可交叉验证，单个 indexer 响应不是最终安全证明。
3. STP 安全依赖有效通道状态、承诺交易、撤销信息、惩罚覆盖和钱包备份。
4. SatoshiNet 节点负责执行和出块，但不替代 BTC L1 的最终边界。
5. 钱包掌握私钥、助记词、授权和关键本地状态。
6. Agent 只能读取证据和调用 adapter，不能保存私钥或绕过签名。

## 主要风险

1. Core Node 离线或拒绝服务。
2. Core Node 广播旧承诺交易。
3. 钱包丢失本地状态或备份。
4. Indexer 分歧、未索引或 reorg。
5. BTC L1 reorg。
6. SatoshiNet 停止出块。
7. 合约漏洞。
8. 公共通道合约和私人 STP 通道的安全模型混淆。

## 不保证什么

1. 聪网状态不等于由 Bitcoin 无条件保证。
2. Indexer 不替用户承担私钥和授权责任。
3. Agent 不替用户承担最终签名决策。
4. 合约资产和私人通道资产有不同安全边界。
5. 测试网验证不代表主网没有风险。

**页面状态：规划中（Planning）**


# 网络经济


# 概述

网络经济部分解释 GAS、费用流、节点质押、节点激励和仍在设计中的经济参数。它服务节点运营者、开发者、社区、赞助方和长期建设者。

## 核心区分

| 概念       | 含义                            |
| -------- | ----------------------------- |
| Gas Unit | 计算、存储和执行资源的计量单位               |
| GAS 资产   | 购买 Gas Unit、支付交易费并用于节点质押的协议资产 |

## 当前设计约束

1. GAS 计划由 BTC L1 上的协议发行。
2. 总量固定。
3. 通过 Transcend / STP 进入聪网。
4. 用于交易和智能合约费用。
5. 挖矿节点与核心节点计划使用 GAS 作为质押物。
6. 合约和交易产生的 GAS 费用当前设计为归出块节点。
7. 当前费用设计不采用基础费销毁。

完整发行、质押、处罚、节点准入、初始分配、基金会治理和法律安排仍在设计中。

**页面状态：设计中（Design in Progress）**


# GAS：网络费用与安全资产

GAS 是聪网的网络费用与安全质押资产。它连接网络使用、节点服务和长期安全。

## GAS 用于什么

1. 支付交易费用。
2. 支付智能合约执行费用。
3. 为网络资源定价。
4. 防止滥用。
5. 支持挖矿节点和核心节点的安全质押设计。

## GAS 不是什么

1. GAS 不代表 SAT20 Labs 或未来基金会股权。
2. GAS 不代表利润分配、回购或固定收益承诺。
3. 节点质押不是固定理财产品。
4. 官网和 Docs 不提供价格预测、收益率或交易所路线承诺。

## 当前状态

完整 GAS 发行、穿越、质押、处罚、节点准入、初始分配与基金会治理规则仍需完成技术模拟、公开讨论和法律审查。

**页面状态：设计中（Design in Progress）**


# 费用流与节点激励

聪网的费用与激励来自真实网络使用，而不是固定收益叙事。

```
用户 / DApp 使用网络
        ↓
支付交易和合约 GAS
        ↓
出块节点获得费用
        ↓
更多独立节点提供执行和网络可用性
        ↓
社区与开发者获得更可靠基础设施
        ↓
更多应用和真实使用
```

## 当前表达边界

1. 节点根据实际提供的网络服务获得协议费用。
2. 不承诺固定 APY。
3. 核心节点覆盖挖矿节点全部功能，因此可以获得其作为出块节点提供网络服务时产生的费用；额外 STP 服务费模型仍在设计中。
4. 社区应用可以根据自己的服务规则设计应用层服务费。
5. 流动性伙伴可以获得应用协议明确产生的费用，同时自行承担市场、合约和流动性风险。

**页面状态：设计中（Design in Progress）**


# 挖矿节点 / 核心节点质押

挖矿节点和核心节点计划使用 GAS 作为质押物。质押用于提高节点承担网络职责的成本，并为处罚和退出规则提供基础。

## 设计中参数

1. GAS 协议名称和资产标识。
2. 挖矿节点质押门槛。
3. 核心节点质押门槛。
4. 解除质押时间。
5. 作恶和离线处罚。
6. 核心节点是否有独立 STP 服务费。
7. 节点准入和退出流程。

**页面状态：设计中（Design in Progress）**


# 设计中问题

本页记录 GAS、节点和网络经济中仍未最终确定的问题，避免把设计中内容误读为最终协议。

## 当前开放问题

1. GAS 协议名称和资产标识。
2. Mining Node 与 Core Node 的差异化质押要求，其中 Core Node 覆盖 Mining Node 能力并承担额外 STP 责任。
3. 解除质押时间。
4. 作恶和离线处罚。
5. Core Node 是否有独立 STP 服务费。
6. 网络安全储备释放曲线。
7. 节点奖励如何随真实费用增长而调整。
8. Paymaster 和社区代付机制。
9. GAS 在 L1 与聪网之间的退出和供应核对规则。
10. 基金会治理、Treasury Policy、地址透明度和法律结构。

**页面状态：设计中（Design in Progress）**


# AI Agent：自动化与安全


# 概述

AI Agent 部分关注一个问题：如何让 Agent 在不接触私钥、不绕过授权的前提下，帮助用户安全操作 BTC L1 与聪网资产，并逐步帮助 BTC 社区规划和部署自己的基础设施。

SAT20 的判断是：越复杂的协议，越需要 Agent 帮用户理解和验证。STP 的承诺交易、惩罚交易、跨层状态和异常恢复，对 Agent 来说是可以读取和推理的证据。

## 两条产品线

| 产品线                     | 目标                                                |
| ----------------------- | ------------------------------------------------- |
| Agent Wallet & Safety   | 帮助用户在钱包安全边界内验证和操作资产                               |
| Community Builder Agent | 帮助 BTC 社区通过对话规划 DEX、DAO、钱包、Indexer、Explorer 和合约模块 |

## 入口

1. [比特币生态 AI Agent 资产安全评估规范](/ai-agent-zi-dong-hua-yu-an-quan/bitcoin-agent-safety-standard)
2. [AI Agent 与用户资产控制](/learn-li-jie-cong-wang/ai-agent)
3. [SAT20 Agent Wallet 安装与使用](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/sat20-agent-wallet)
4. [SAT20 Agent Wallet 互操作技能规范](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/interoperability)
5. [SAT20 Agent Wallet 资产安全控制指南](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/asset-safety)
6. [SAT20 Agent Wallet 验证矩阵与数据缺口](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/verification-and-data-gaps)
7. [SAT20 Agent Wallet 测试网验证记录](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/testnet-validation)
8. [SAT20 Agent Wallet 1 分钟演示视频](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/demo-video)
9. [Community Builder Agent](/ai-agent-zi-dong-hua-yu-an-quan/community-builder-agent)

## 基本原则

1. Agent 不保存私钥。
2. Agent 不保存助记词。
3. Agent 不绕过钱包授权。
4. Agent 不只看余额。
5. Agent 必须检查承诺交易和惩罚覆盖。
6. Agent 发现安全证据缺失时必须停止价值移动。

## 长期方向

1. 钱包 Agent：帮助用户安全管理跨层资产。
2. 合约 Agent：解释和执行合约操作。
3. 风控 Agent：发现异常状态和旧承诺广播。
4. 社区 Agent：回答文档、测试网和开发者问题。
5. Community Builder Agent：帮助社区生成部署架构、配置、合约参数和验收报告。


# 比特币生态 AI Agent 资产安全评估规范

本文定义一套面向比特币生态项目的 AI Agent 资产安全评估规范。它不是 SAT20 专属规范，也不是投资评级。它的目标是让任何 AI Agent 在帮助用户使用比特币生态项目之前，能用同一套原则检查：用户资产是否仍由用户控制，项目是否能提供可验证证据，异常时用户是否能安全退出。

这套规范只关注资产安全，不评价价格、收益、市场热度或叙事强弱。

## 核心目标

一个用户可信赖的比特币生态 AI Agent，首先必须保护用户资产安全。它先问资产安全问题，再评估项目功能：

1. 用户是否仍持有私钥或最终控制权。
2. 资产是否托管给第三方。
3. 资产状态能否由 BTC L1、UTXO、交易、脚本、承诺交易、索引器或公开证明复核。
4. 项目方离线、失败、作恶或接口不可用时，用户是否仍能退出。
5. Agent 是否能在价值移动前自动发现风险并停止。

如果这些问题无法回答，Agent 停止替用户执行价值移动操作。

## 适用范围

本规范适用于比特币生态中的：

| 类型          | 示例                               |
| ----------- | -------------------------------- |
| 钱包          | 移动钱包、PWA 钱包、硬件钱包集成               |
| 跨层协议        | 通道、桥、侧链、L2、资产映射协议                |
| 资产协议        | Ordinals、Runes、BRC20、ORDX 等      |
| 交易平台接入      | 充值、提现、跨层入金和出金                    |
| 智能合约网络      | 使用 BTC L1 资产作为入口或结算资产的应用网络       |
| AI Agent 钱包 | 通过 adapter 或 skill 操作钱包和协议的自动化代理 |

本规范不要求所有项目都采用同一种技术路线。它只要求项目能向 Agent 解释资产控制权、可验证证据和异常退出路径。

## 不可妥协原则

### 1. 私钥不进入 Agent

Agent 不保存用户助记词、私钥、硬件钱包种子或可直接转移资产的长期秘密。签名发生在钱包、硬件设备、PWA、受权限控制的本地 adapter 或用户明确授权的签名环境中。

### 2. 授权不可绕过

任何主网价值移动都必须经过用户可理解的授权。授权信息至少包括网络、资产、金额、目标地址、费用、操作类型和风险提示。

### 3. 余额不是安全证明

余额显示只是结果，不是资产安全证明。Agent 必须能追溯资产来自哪个 UTXO、交易、通道、承诺状态、合约状态或 indexer 证据。

### 4. 服务方状态不等于事实

项目方 API、Core Node、桥服务、交易平台或单个 indexer 的返回都不是最终事实。Agent 必须优先使用链上交易、可复算规则、签名、证明材料和多源查询来验证状态。

### 5. 退出路径必须可描述

如果用户资产进入某个协议、通道、L2 或合约，Agent 必须能说明用户如何退出：协商退出、强制退出、惩罚旧状态、等待时间锁、提交证明、提现到 BTC L1，或其他可验证路径。

### 6. 结果未知必须保守处理

当广播交易、跨层请求或协议协商返回 timeout、EOF、连接中断或状态未知时，Agent 不得直接重试同一价值移动操作。它必须先查询链上和协议状态，判断交易是否可能已经成功。

### 7. 主网和测试网必须隔离

故障注入、旧状态广播、惩罚演练、测试资产和不安全接口只能在测试网使用。Agent 必须拒绝在主网调用测试接口。

## 评分模型

Agent 可以按 100 分评估一个项目的资产安全成熟度：

| 维度          | 分值 | Agent 要检查什么                                   |
| ----------- | -: | --------------------------------------------- |
| 私钥与授权边界     | 15 | 私钥是否留在用户钱包；价值移动是否需要用户授权                       |
| BTC L1 可验证性 | 15 | 资产入口、退出、UTXO、txid、确认数是否可复核                    |
| 资产事实层       | 10 | 是否有 indexer、证明或可复算规则表达资产状态                    |
| 退出能力        | 15 | 用户在对方离线或失败时是否能退出                              |
| 作恶惩罚或风险限制   | 10 | 对旧状态、双花、无效证明、欺诈行为是否有惩罚或限制                     |
| 网络不确定性处理    | 10 | timeout / EOF / reorg / mempool / 未索引时是否保守处理  |
| Agent 可操作接口 | 10 | 是否有稳定 adapter、只读查询、安全快照和事务轮询                  |
| 证据可读性       | 10 | 是否能输出 txid、vout、承诺交易、状态高度、explorer/indexer 链接 |
| 测试网可验证演练    |  5 | 是否有用户和 Agent 可复现的测试网流程                        |

评分解释：

|     分数 | 结论                            |
| -----: | ----------------------------- |
| 90-100 | Agent 可高度信任其资产安全模型，但仍需按操作逐项验证 |
|  75-89 | 安全模型较强，适合受控使用；需要补齐部分证据或接口     |
|  60-74 | 可测试或小额使用；主网大额操作需要额外人工审查       |
|  40-59 | Agent 只提供解释和风险提示，不自动执行主网价值移动  |
|   0-39 | 资产安全证据不足，Agent 应拒绝代表用户操作      |

## Agent 评估流程

Agent 评估一个项目时，应按以下步骤执行：

1. 识别资产类型：BTC、Ordinals、Runes、BRC20、ORDX 或其他协议资产。
2. 识别控制模型：自托管、多签、通道、托管桥、合约锁定、交易平台账户或其他模型。
3. 查询链上事实：txid、vout、地址、脚本、确认数、是否花费、协议事件是否有效。
4. 查询协议状态：通道、合约、L2、桥、订单或 pending 事务状态。
5. 检查用户控制权：私钥、签名权限、承诺交易、退出交易、惩罚材料或提现权限。
6. 检查异常路径：对方离线、接口不可用、reorg、交易未知、旧状态、无效证明。
7. 给出评分和阻断项：列出可以继续的操作、必须停止的操作和缺失证据。

## Agent 输出格式

Agent 应输出结构化评估，便于用户、钱包和其他 Agent 复核：

```json
{
  "standard": "bitcoin-agent-asset-safety",
  "version": "0.1",
  "project": "example",
  "network": "mainnet|testnet",
  "score": 0,
  "level": "BLOCKED|TEST_ONLY|CONTROLLED_USE|HIGH_CONFIDENCE",
  "dimensions": [
    {
      "name": "private_key_and_authorization",
      "score": 0,
      "max": 15,
      "evidence": [],
      "missing": [],
      "risk": ""
    }
  ],
  "must_stop": [],
  "allowed_actions": [],
  "next_checks": []
}
```

Agent 输出分数，同时附带证据和缺口。

## SAT20 / 聪网评估

以下评估使用同一套规范审视 SAT20 / 聪网。它不是最终结论，而是当前文档和测试网演练基础上的可更新评估。

| 维度          |      分值 | SAT20 当前评估                                                                                                 |
| ----------- | ------: | ---------------------------------------------------------------------------------------------------------- |
| 私钥与授权边界     | 14 / 15 | 推荐形态是 SAT20 PWA Wallet 保存私钥和授权，SAT20 Agent Wallet 只通过 adapter 发起请求，不保存助记词                                  |
| BTC L1 可验证性 | 14 / 15 | STP funding、splicing、close、punish 都能回到 BTC L1 txid、UTXO 和承诺交易验证                                            |
| 资产事实层       |  9 / 10 | BTC L1 indexer + 聪网 L2 indexer 共同表达资产事实；L2 indexer 随节点集成，Core Node 要求自己的 L1 indexer                        |
| 退出能力        | 14 / 15 | 用户持有最新承诺交易；Core Node 离线时可强制关闭；CSV 后可 sweep                                                                 |
| 作恶惩罚或风险限制   | 10 / 10 | 对已撤销旧状态有 punish 机制，测试网已完成旧 Core Node commitment 惩罚演练                                                       |
| 网络不确定性处理    |  8 / 10 | 文档和 skill 已明确未知结果必须按“可能成功”处理；仍需更多主网前长时间运行验证                                                                |
| Agent 可操作接口 |  8 / 10 | `sat20-agent-wallet` 已定义 adapter contract、安全快照、commitment export、punish、transaction 轮询；PWA adapter 还需继续产品化 |
| 证据可读性       |  8 / 10 | 测试网已形成 txid、commit height、punish tx 和 indexer 证据；还需统一 explorer/indexer 链接包 schema                          |
| 测试网可验证演练    |   5 / 5 | 已完成 STP 通道、splicing、unlock/lock、旧 commitment 广播和 punish drill                                              |

综合评分：`90 / 100`。

评估等级：`HIGH_CONFIDENCE`，含义是 SAT20 的资产安全模型具备较强的可验证基础，Agent 可以在证据完整、钱包授权明确、网络一致的前提下辅助用户操作；主网大额操作仍应逐项执行安全快照和用户确认。

## SAT20 的关键证据

SAT20 获得高分的原因不是“相信 Core Node”，而是以下证据可由 Agent 检查：

1. 资产进入用户与 Core Node 的 2-of-2 通道地址。
2. 用户钱包持有最新承诺交易。
3. 承诺高度单调前进。
4. 已撤销旧状态有 punish coverage。
5. Core Node 广播旧状态时，用户钱包可以构造并广播惩罚交易。
6. L1/L2 indexer 能把 BTC L1 UTXO、ascend、descend、通道状态和聪网 UTXO 串成证据链。
7. SAT20 Agent Wallet 不接触私钥，只通过钱包 adapter 操作。

## SAT20 仍需补齐的内容

为了让任何第三方 Agent 更稳定地使用这套规范评估 SAT20，还需要继续补齐：

1. PWA adapter 的完整 `wallet.transaction` / `stp.transaction` 轮询 schema。
2. 每个 txid 的 L1/L2 explorer URL、indexer URL 和状态字段标准化。
3. `stp.safety_snapshot` 在 PWA 中的产品化展示。
4. 更完整的主网前长时间运行、reorg、未索引、Core Node 离线和重复请求测试。
5. 面向普通用户的风险解释 UI：为什么当前可继续、为什么必须停止、缺失哪类证据。

## Agent 对 SAT20 的默认动作策略

当 Agent 使用 SAT20 Agent Wallet 操作 SAT20 / STP 时，应默认执行：

1. 先让用户安装并初始化 SAT20 PWA Wallet，确保私钥和授权边界在钱包内。
2. 再安装或调用 SAT20 Agent Wallet skill。
3. 价值移动前读取 `stp.safety_snapshot`。
4. 如果缺少最新承诺交易、punish coverage、L1/L2 indexer 证据或用户授权，停止操作。
5. 如果网络结果未知，进入轮询和恢复流程，不立即重试。
6. 如果 Core Node 离线，优先给出 force-close plan。
7. 如果 Core Node 广播旧状态，优先构造并广播 punish tx。

这就是 SAT20 Agent Wallet 应建立在本规范之上的原因：Agent 不是为了替用户冒险自动化，而是为了让用户资产安全变得可读、可验证、可执行。


# Community Builder Agent

Community Builder Agent 的目标是让 BTC 社区通过几轮对话，设计并逐步部署自己的 DAO、DEX、钱包、Indexer、Explorer 和合约模块。

后续页面会补充模块输入输出、JSON Schema、工具调用、部署流程、钱包授权、错误码、验证证据和社区报告模板。

**页面状态：开发中（In Development）**


# SAT20 Agent Wallet


# 安装与使用

> 本文说明如何安装和使用通用 SAT20 Agent Wallet skill，让 AI Agent 通过 SAT20 钱包适配器操作 SAT20 Wallet、STP 通道、BTC L1 资产和聪网资产。Codex 可以直接使用本文中的 skill 包；其他 Agent 也可以读取同一 `SKILL.md`、references 和 scripts 接入。

## 演示视频

* [1 分钟中文有声版演示视频](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/demo-video)

## 设计目标

SAT20 Agent Wallet 建立在 [比特币生态 AI Agent 资产安全评估规范](/ai-agent-zi-dong-hua-yu-an-quan/bitcoin-agent-safety-standard) 之上。Agent 在操作 SAT20/STP 之前，应先用这套通用规范判断资产控制权、退出能力、链上证据、Core Node 风险和缺失数据，再决定是否允许价值移动。

SAT20 Agent Wallet skill 的目标不是把私钥放进 AI Agent，也不是把某一种语言的钱包实现写死在 skill 中。它采用三层结构：

1. Skill：定义 Agent 工作流、安全护栏、操作剧本和适配器契约。
2. 适配器调用脚本：把 Agent 的 JSON 请求转发给 SAT20 PWA Wallet Adapter 或第三方 SAT20 钱包客户端。
3. 钱包适配器：真正管理私钥、构造交易、签名、持久化钱包和通道状态，并与 indexer、SatoshiNet 和 Core Node 通信。

这样，任何团队都可以用 Go、JS、Python、Rust 或其他语言实现自己的 SAT20 钱包适配器，只要满足统一 JSON 适配器契约，AI Agent 就能通过同一个 skill 操作它。

面向普通用户的推荐形态是：用户安装 SAT20 PWA Wallet，PWA 内部加载 `sat20wallet.wasm` 和 `stpd.wasm`，SAT20 Agent Wallet 通过 PWA 暴露的受权限控制 adapter 发起 STP 操作。这样私钥、助记词、钱包数据库、交易确认和授权弹窗都留在 PWA 内，Agent 只拿到用户授权后的协议操作结果。

## 推荐安装顺序

面向普通用户和主网场景，先安装 SAT20 PWA Wallet，再安装 SAT20 Agent Wallet skill。

原因很简单：PWA 钱包是安全边界，负责私钥、助记词、钱包密码、签名、授权弹窗、钱包数据库和通道状态；skill 是 Agent 的操作知识、工作流和安全检查清单。Agent 应通过 PWA adapter 调用钱包，而不是替代钱包。

推荐顺序：

1. 安装 [SAT20 PWA Wallet](https://sat20.org/pwa/?install=1)。
2. 在 PWA 内创建或导入钱包。
3. 完成助记词备份、密码设置、网络选择和解锁。
4. 在 PWA 中启用或连接受权限控制的 Agent adapter。
5. 安装 SAT20 Agent Wallet skill。
6. Agent 先执行 `wallet.status`、`stp.status` 和 `stp.safety_snapshot`，确认钱包、网络、Core Node、通道和惩罚覆盖状态。
7. 只有安全快照满足要求后，Agent 才发起 open、splicing、unlock、lock、close 或 punish 等操作。

## Skill 目录

可安装 skill 位于：

```
docs/ai/sat20-agent-wallet/skills/sat20-agent-wallet/
```

该 skill 库只在 `sat20-labs/docs` 仓库中维护一份。英文文档或其他站点引用 SAT20 Agent Wallet skill 时，统一链接到本目录或安装脚本，避免复制独立 skill 库。

目录结构：

```
sat20-agent-wallet/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   ├── install.sh
│   ├── stp_adapter.py
│   ├── stp_transcend_rpc_adapter.py
│   └── stp_workspace_wallet_adapter.py
└── references/
    ├── adapter-contract.md
    ├── operation-playbooks.md
    └── pwa-wasm-adapter.md
```

## 安装 Skill

官方 GitBook 文档入口是 [docs.sat20.org](https://docs.sat20.org)。

如果你还没有安装 SAT20 PWA Wallet，请先打开：

```
https://sat20.org/pwa/?install=1
```

[**一键安装 SAT20 Agent Wallet**](https://raw.githubusercontent.com/sat20-labs/docs/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/install.sh)

在终端中执行：

```bash
curl -fsSL https://raw.githubusercontent.com/sat20-labs/docs/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/install.sh | bash
```

该命令默认安装到 `~/.codex/skills/sat20-agent-wallet`。如果目标 Agent 使用不同的 skills 目录，可以指定：

```bash
curl -fsSL https://raw.githubusercontent.com/sat20-labs/docs/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/install.sh | SAT20_SKILLS_DIR=/path/to/agent/skills bash
```

也可以固定安装某个分支：

```bash
curl -fsSL https://raw.githubusercontent.com/sat20-labs/docs/main/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/install.sh | SAT20_DOCS_BRANCH=main bash
```

脚本会从 `https://github.com/sat20-labs/docs` 下载 skill 包，只安装 `ai/sat20-agent-wallet/skills/sat20-agent-wallet` 目录；如果本地已存在同名 skill，会先移动为带时间戳的备份目录。

手动安装时，将整个 `sat20-agent-wallet` 目录复制到目标 Agent 的 skills 目录。对 Codex，可以使用：

```bash
mkdir -p ~/.codex/skills
cp -R docs/ai/sat20-agent-wallet/skills/sat20-agent-wallet ~/.codex/skills/
```

安装后，Codex 可以通过 `$sat20-agent-wallet` 显式调用该 skill。其他 Agent 如果支持 `SKILL.md` 约定，也可以直接读取 `docs/ai/sat20-agent-wallet/skills/sat20-agent-wallet/SKILL.md` 作为入口。

安装 skill 后，第一步不是直接移动资产，而是让 Agent 连接 PWA adapter 并读取 `wallet.status` / `stp.status` / `stp.safety_snapshot`。这些检查能确认 Agent 没有绕过钱包授权，也能确认通道安全材料是否完整。

后续示例使用 `SAT20_AGENT_WALLET_DIR` 表示 skill 安装目录：

```bash
export SAT20_AGENT_WALLET_DIR="docs/ai/sat20-agent-wallet/skills/sat20-agent-wallet"
```

## 配置适配器

skill 支持两种适配器方式。推荐优先使用 SAT20 PWA Wallet Adapter 暴露的 HTTP 或浏览器桥接接口。

新文档统一使用 `SAT20_ADAPTER_URL`、`SAT20_CLIENT_CMD`、`SAT20_SKILLS_DIR` 等变量。为了兼容已有测试网工具，安装脚本和转发脚本仍接受旧的 `STP_ADAPTER_URL`、`STP_CLIENT_CMD`、`STP_SKILLS_DIR`。

### PWA Wallet Adapter

用户安装并解锁 SAT20 PWA Wallet 后，由 PWA 提供一个受权限控制的 SAT20 wallet adapter。Agent 设置：

```bash
export SAT20_ADAPTER_URL="http://127.0.0.1:19530/stp-adapter"
```

或设置一个本地 CLI wrapper，把 JSON 请求转发给 PWA 的 DApp Connect / postMessage 桥接。

PWA adapter 内部调用 `sat20wallet.wasm` 和 `stpd.wasm` 完成钱包与 STP 操作。Agent 不直接加载 WASM，也不保存私钥。

当前 PWA DApp Connect 桥已经暴露 `wallet.*` 和 `stp.*` 标准方法。`wallet.status` / `stp.status` 是只读查询；创建/导入/导出助记词、改密、发送资产和通道状态变更操作会进入 PWA 的 Agent Operation 授权弹窗，用户确认后再执行。

`wallet.send_assets` 是 Agent 可控钱包的基础能力。Agent 只提交转账意图：网络、资产、金额、目标地址和可选备注；PWA 负责自动选币、估费、构造交易、展示预览、请求用户授权、签名广播和返回 txid。Agent 不应直接持有私钥、助记词或绕过 PWA 授权，也不应默认要求用户手工选择 asset UTXO 或 fee UTXO。

当前限制：PWA 侧 `wallet.transaction` / `stp.transaction` 轮询还需要继续标准化；后续应在 PWA 内补齐交易、reservation、L1/L2 可见性和下一步建议。

### 本地测试钱包 Adapter

在 SAT20 本地 workspace 中测试 skill 时，可以使用开发 adapter 创建 testnet 钱包：

```bash
SAT20_CLIENT_CMD="python3 docs/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_workspace_wallet_adapter.py" \
python3 docs/ai/sat20-agent-wallet/skills/sat20-agent-wallet/scripts/stp_adapter.py --pretty '{"op":"wallet.create","chain":"testnet"}'
```

该 adapter 只用于 testnet bootstrap，生成的助记词应导入 SAT20 PWA Wallet；后续 STP 操作仍应由 PWA Adapter 授权执行。

### CLI 适配器

设置 `SAT20_CLIENT_CMD`：

```bash
export SAT20_CLIENT_CMD="stp-client --json"
```

Agent 会通过 skill 内置脚本调用：

```bash
python3 "$SAT20_AGENT_WALLET_DIR/scripts/stp_adapter.py" '{"op":"stp.status","chain":"testnet"}'
```

脚本会把 JSON 请求追加到 `SAT20_CLIENT_CMD` 后面，并解析适配器返回的 JSON。

### 本地 STP 适配器

如果本机已经运行兼容 STP 服务，可以使用 skill 内置的本地 adapter，将统一 JSON 操作映射到本地 STP 客户端能力：

```bash
export SAT20_CLIENT_CMD="python3 $SAT20_AGENT_WALLET_DIR/scripts/stp_transcend_rpc_adapter.py"
```

该 adapter 适合 testnet 自动化，支持 wallet import/unlock 以及 open/close/splicing-in/splicing-out/lock/unlock/lock-with-expand。异常恢复场景下还支持 `stp.clean_channel`，用于链上已确认关闭或惩罚、但 adapter 仍能看到旧 active channel 时的清理；清理后应走 ordinary `stp.open` + `stp.expand`，不能把它当作普通关闭通道的替代操作。

当前 testnet adapter 已能通过 `stp.safety_snapshot` 返回 `NO_REVOKED_REMOTE_STATE` 或 `COVERED`，Agent 可以直接据此判断是否允许继续价值移动。完整 L1/L2 余额、UTXO、PWA WASM 状态和用户授权状态应由 PWA adapter 补齐。

`stp.safety_snapshot` 还应区分承诺资产余额与 L2 可花费 UTXO。`local_balance` / `remote_balance` 表示当前承诺交易中的资产分配；`l2_spendable_balance` / `l2_pending_balance` 表示这些资产在 SatoshiNet UTXO 集中的可花费状态。Agent 发起 unlock/lock 前必须确认目标资产已经位于 `l2_spendable_balance`，不能只因为它出现在承诺资产集合中就继续操作。刚 splicing-in 的资产可能已经进入 commitment，但 anchor 输出仍在 `pendingUtxosL2`。

`stp.transaction` 应返回 Agent 可使用的 reservation 状态、相关 txid、channel id、错误码和下一步建议。如果链上交易已广播但未确认，Agent 应继续轮询，不得重复发起同一价值移动操作。

### HTTP 适配器

设置 `SAT20_ADAPTER_URL`：

```bash
export SAT20_ADAPTER_URL="http://127.0.0.1:19530/stp-adapter"
```

skill 内置脚本会向该 URL 发送 JSON POST 请求。

## 适配器职责

适配器必须完成真正的钱包和协议操作：

1. 管理用户私钥或连接安全钱包；推荐由 SAT20 PWA Wallet 完成。
2. 与 Core Node 通信。
3. 构造、签名和广播 BTC L1 / SatoshiNet / STP 交易。
4. 保存通道状态、承诺交易、撤销材料和未完成事务。
5. 返回统一 JSON 响应给 Agent。

skill 只负责 Agent 工作流，不负责保管私钥。

## 支持操作

适配器至少应支持三组操作。

### 钱包管理

| 操作                       | 目的                        |
| ------------------------ | ------------------------- |
| `wallet.create`          | 创建 testnet 钱包或请求 PWA 创建钱包 |
| `wallet.import`          | 把助记词导入 PWA 钱包             |
| `wallet.export_mnemonic` | 经 PWA 授权后导出助记词            |
| `wallet.change_password` | 经 PWA 授权后修改钱包密码           |
| `wallet.status`          | 查询 PWA 钱包和 WASM 初始化状态     |
| `wallet.send_assets`     | 直接从钱包地址发送 BTC L1 或聪网资产    |
| `wallet.transaction`     | 查询普通钱包交易状态                |

### 通道管理

| 操作                              | 目的                                                |
| ------------------------------- | ------------------------------------------------- |
| `stp.status`                    | 查询钱包、Core Node、通道和链状态                             |
| `stp.open`                      | 打开通道                                              |
| `stp.reopen`                    | 通道关闭后恢复同一个 client-core channel，必要时创建新的 L1 funding |
| `stp.rebuild`                   | 根据 L1/L2 ledger 证据重建通道状态，避免重复 anchor              |
| `stp.restore`                   | 从 peer、备份或本地持久化状态恢复通道                             |
| `stp.expand` / `stp.expand_all` | 将已经位于通道地址但未纳入承诺状态的资产纳入通道管理                        |
| `stp.unlock`                    | 通道资产释放到聪网个人地址                                     |
| `stp.lock`                      | 聪网个人资产回锁到通道                                       |
| `stp.lock_with_expand`          | 容量不足时通过穿越合约和 expand 恢复通道控制权                       |
| `stp.splicing_in`               | L1 资产进入通道                                         |
| `stp.splicing_out`              | 通道资产退出到 L1                                        |
| `stp.close`                     | 协商关闭或强制关闭通道                                       |
| `stp.transaction`               | 查询未完成 STP 事务                                      |

### 资产安全管理

| 操作                                              | 目的                                               |
| ----------------------------------------------- | ------------------------------------------------ |
| `stp.safety_snapshot`                           | 查询通道点、commit height、承诺交易、余额、CSV 和惩罚覆盖            |
| `stp.commitment_export`                         | 导出当前承诺交易和只读校验材料，不导出私钥或 revocation secret         |
| `stp.punish_status`                             | 查询已撤销 remote commitment 的 punish coverage        |
| `stp.punish_build`                              | 对指定旧 commitment 构造并 dry-run 验证惩罚交易               |
| `stp.punish_broadcast`                          | 广播已验证的惩罚交易                                       |
| `stp.force_close_plan`                          | 生成本地强制关闭计划，证明用户可单方面退出                            |
| `stp.sweep_build`                               | CSV 到期后构造、签名并验证 sweep tx；默认 dry-run，可在钱包授权后广播    |
| `stp.test_retain_server_commitment`             | 测试网让 Core Node 保留 Core Node 侧旧 commitment，主网不可用  |
| `stp.test_broadcast_retained_server_commitment` | 测试网让 Core Node 广播 Core Node 侧旧 commitment，触发惩罚演练 |

完整契约见：

* `skills/sat20-agent-wallet/references/adapter-contract.md`
* `skills/sat20-agent-wallet/references/pwa-wasm-adapter.md`

## Agent 工作流

Agent 安装 skill 后，应按以下流程操作：

1. 连接 SAT20 PWA Wallet adapter 或其他受控钱包 adapter，确认私钥、密码、助记词和签名仍在钱包安全边界内。
2. 调用 `wallet.status` 或 `stp.status`，确认网络、钱包、Core Node、通道状态。
3. 根据用户目标选择操作：
   * 钱包管理：create、import、export mnemonic、change password。
   * 普通转账：wallet.send\_assets。
   * BTC L1 到聪网：open + splicing-in / expand。
   * 通道到聪网个人地址：unlock。
   * 聪网个人地址回通道：lock；容量不足时 lock-with-expand。
   * 通道到 BTC L1：splicing-out。
   * 永久退出：优先 cooperative close，异常时 force close。
4. 主网价值转移前要求用户在 PWA 钱包内确认资产、金额、地址、费率、通道和操作。
5. 每次价值移动前后都运行 `stp.safety_snapshot`；如果缺少承诺交易或 punish coverage，停止普通操作。
6. 如果 `stp.punish_status` 返回 `NO_REVOKED_REMOTE_STATE`，表示当前没有已撤销对方旧状态需要覆盖；如果返回 `COVERED`，表示已撤销状态均有 verified/broadcastable punish tx。只有这两种状态允许继续普通价值移动。
7. 如果 `stp.punish_status` 无法证明 coverage，归一化为 `PUNISH_COVERAGE_UNKNOWN`，停止普通价值移动，先要求钱包或 STP adapter 重新导出可验证证据。
8. 如果 `stp.safety_snapshot` 返回 `READY_DEGRADED`，只允许只读跟踪。典型场景是 reopen/open funding 已广播但 L1 未确认，或 adapter 正在恢复；此时不能继续 unlock、lock、splicing、close 或 punish drill。
9. 发起操作后轮询 `stp.transaction`。
10. 返回 txid、事务状态、通道状态和下一步建议。

测试网安全演练时，Agent 应按 `references/operation-playbooks.md` 中的 Testnet Punish Drill 执行：先演示 Runes/BRC20 splicing、L2 unlock/lock，再使用测试网故障注入接口触发Core Node 侧旧 commitment 广播，最后用 `stp.punish_build` / `stp.punish_broadcast` 证明惩罚能力。

真实测试网演练的总结见 [测试网演练总结](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/testnet-drill-summary-2026-06-13)。后续维护 skill 时，应优先从这份总结提炼 Agent 安全能力：价值移动前必须验证 `READY_SAFE`，刚 ascend 的资产必须等待 `l2_spendable_balance`，未知网络结果必须按“可能成功”处理，Core Node 侧旧 commitment 被广播时必须优先 punish，旧通道不能继续普通运行时应重新建立可证明安全的控制边界。

Agent 具体如何验证这些条件，以及 PWA adapter / indexer 还需要补充哪些数据，见 [验证矩阵与数据缺口](/ai-agent-zi-dong-hua-yu-an-quan/sat20-agent-wallet/verification-and-data-gaps)。安装 skill 的 Agent 应把该文档作为安全验证清单，而不是只依赖操作成功或余额变化。

## 安全边界

1. SAT20 Agent Wallet 不保存私钥。
2. SAT20 Agent Wallet 不绕过钱包授权。
3. 导出助记词、修改密码必须在 PWA 钱包内确认，钱包密码不进入 Agent 对话。
4. mainnet 操作必须明确确认。
5. 核心节点状态不能被盲目信任，交易、签名、资产和承诺高度必须由适配器校验。
6. lock 容量不足时，Agent 应优先使用 lock-with-expand，保障用户随时恢复 BTC 主网承诺交易兜底的控制权。
7. Agent 不能把 punish coverage 查询失败当成安全；无法证明惩罚覆盖时，默认停止新的通道价值移动。




---

[Next Page](/llms-full.txt/1)