互操作技能规范
本文面向需要自动操作 SAT20 Wallet 与 STP 通道的 AI Agent。目标是让 Agent 能够安全地理解、查询和执行资产在 BTC L1 与聪网之间的迁移。本文不是运行时代码，也不是某个 Agent 本地安装的
SKILL.md，而是SAT20 Agent Wallet的协议操作规范。
技能目标
Agent 应掌握以下能力：
判断资产当前位于 BTC L1、聪网个人地址还是 STP 通道。
判断是否已有可用通道，以及通道是否 ready。
根据用户目标选择 open、splicing-in、unlock、lock、lock-with-expand、splicing-out 或 close。
发起操作后围绕
txId和resvId追踪状态。遇到未确认、peer offline、UTXO locked、channel busy、insufficient fee 等情况时安全停止或重试。
优先接口
Agent 优先使用经过封装的 STP 客户端接口，避免直接拼装节点间底层协商消息。
原因：
高层客户端接口应自动选择 UTXO、构造交易、签名、保存事务、广播交易和发送 peer 消息。
底层协商消息需要手工构造签名、commitment、revocation 和中间消息，出错风险高。
只有在实现 STP 客户端库或调试协议兼容性时，才应直接处理底层消息。
前置检查
每次执行资产操作前，Agent 必须检查：
钱包是否存在并已解锁
未解锁不能签名
STP 服务是否 ready
L1/L2 同步和通道监控未就绪时停止操作
当前网络 chain / env
防止 mainnet/testnet 混用
L1/L2 indexer 是否可查询
资产和确认状态依赖 indexer
Core Node 是否在线
通道协作需要 peer
是否已有 ready 通道
决定 open 还是直接操作
资产名称和 divisibility
金额必须按 ticker 精度解析
UTXO 是否已被 reservation 锁定
防止重复花费
操作是否涉及 BRC20/Runes
这些资产可能需要 inscription 或长时间确认
价值移动前的安全门
STP 的核心安全性来自承诺交易和惩罚交易，而不是来自 Core Node 的信用声明。因此，Agent 在任何 open 之后的价值移动操作前，都必须先取得通道安全快照。
最低安全快照应包含：
channelId / chanPoint
当前承诺交易输入必须指向最新通道点
commitHeight
必须单调递增，不能回退
localCommitment
用户必须持有可广播的最新本地承诺交易
remoteCommitment
必须能识别对方可能广播的承诺交易
localBalance / remoteBalance
余额必须与承诺交易输出和资产根一致
csvDelay
强制关闭后的清扫窗口必须可被用户接受
punishCoverage
已撤销的对方旧承诺必须有可构造或可广播的惩罚交易
stateBackup
最新通道状态和未完成事务必须已持久化
如果无法取得这些信息，Agent 应把通道标记为 READY_DEGRADED，停止 splicing、unlock、lock、close 等价值移动操作，并向用户报告 SAFETY_SNAPSHOT_REQUIRED 或 PUNISH_COVERAGE_MISSING。只有当钱包或 STP adapter 能重新证明最新承诺交易和惩罚覆盖后，才允许继续操作。
punishCoverage 应至少区分以下状态：
NO_REVOKED_REMOTE_STATE
当前没有已撤销的对方旧承诺需要惩罚覆盖
可继续，但后续每次状态推进后必须再次检查
COVERED
已撤销 remote commitment 均有 verified / broadcastable punish tx
可继续普通价值移动
PUNISH_COVERAGE_UNKNOWN
adapter 无法给出可验证的惩罚覆盖结论
停止价值移动
PUNISH_COVERAGE_MISSING
已发现 revoked commitment，但缺少可验证惩罚交易
停止价值移动并进入安全恢复
Agent 不能只因为通道是 READY 就执行操作。READY_SAFE 的最低标准是：承诺交易存在、commit height 单调、余额一致，并且 punish coverage 处于 NO_REVOKED_REMOTE_STATE 或 COVERED。
READY_SAFE 也不等于所有资产 UTXO 都已经可花费。刚 splicing-in 或 expand 的资产，可能已经出现在承诺资产集合中，但对应 SatoshiNet anchor 输出仍在 pendingUtxosL2。Agent 在 unlock/lock 前必须确认目标资产已经进入可花费 UtxosL2，或 adapter 的 l2_spendable_balance 已覆盖该资产；如果它仍在 l2_pending_balance，只能轮询等待，不能重试 unlock。
核心决策树
目标：把 BTC L1 资产带入聪网
如果没有通道：
发起 open 创建白聪通道。
等待通道进入 ready 状态。
如果资产已经在通道地址但未纳入管理：
发起 expand 类 STP 纳管动作。
如果资产在用户 L1 地址：
发起 splicing-in。
完成后查询事务状态和聪网资产摘要。
目标：恢复已经关闭但仍有资产的通道
查询通道地址的 BTC L1 UTXO、SatoshiNet L2 资产和 channel ledger。
如果 ledger 证明该通道地址曾经打开过，优先发起
stp.reopen，恢复同一个 client-core channel。如果通道地址上没有满足最小容量要求的白聪 UTXO，让 reopen 路径由用户钱包提供新的 L1 funding 输出。
funding 交易可见但未确认时，不重复 reopen，不执行 unlock / lock / splicing，只轮询 funding、reservation、local/core channel status。
等待 funding 确认且双方进入 ready 后，立即运行
stp.safety_snapshot，再继续后续资产流转或 punish drill。
目标：在聪网自由使用通道资产
查询通道是否 ready。
查询通道中该资产余额是否足够，并确认目标资产已经在可花费
UtxosL2/l2_spendable_balance中。发起 unlock。
等待 unlock 事务确认。
查询聪网个人地址资产余额。
目标：把聪网个人资产重新纳入通道保护
查询通道是否 ready。
查询聪网个人地址是否有足够资产余额；具体资产输入和手续费输入由 adapter 内部选择。
如果通道容量足够：
发起 lock。
如果通道容量不足：
发起 lock-with-expand。
该路径通过穿越合约和 expand 将聪网个人资产重新纳入用户通道控制。
等待 lock 或 lock-with-expand 相关 reservation 确认。
目标：把聪网资产退回 BTC L1
如果资产仍在通道中：
发起 splicing-out，目标地址必须是有效 BTC 地址。
如果资产在聪网个人地址，应先通过 lock 或 lock-with-expand 重新纳入通道，再按通道退出路径处理。
如果要永久退出通道：
优先发起协商关闭。
peer 不在线或异常时才使用强制关闭。
追踪聪网侧退出状态和 BTC L1 splicing-out/close 交易确认。
补充规则：
Runes / BRC20 等协议资产 splicing-out 通常需要 BTC L1 fee。Agent 不选择 fee 输入；adapter 必须在内部选择合适的纯白聪输入，不能把带资产的 UTXO 当作普通 fee 输入。
如果 adapter 返回 fee 不足，Agent 提示用户补充普通 BTC fee 资金，待确认后再重试；fee 输入仍由 adapter 内部选择。
BRC20 splicing-in / splicing-out 所需的 transfer 输出由 adapter 内部选择；没有合适 transfer 输出时，adapter 应自动铸造合适的 transfer inscription。
BRC20 全量 splicing-out 后，如果安全快照显示该 BRC20 通道余额已为
0，Agent 可以继续；若余额非0且资产 UTXO 已不可验证，必须视为资产一致性风险并停止。BRC20 splicing-in 时，Agent 只提供资产名和金额，不传 transfer 输出；adapter 根据钱包资产状态选择已有 transfer 输出或自动生成新的 transfer inscription。
一个 L1 UTXO 可能同时携带多种资产。当前 STP splicing-in 只 ascend 请求参数明确指定的资产；同一 UTXO 中未指定的 ORDX、Runes、BRC20 transfer 或 Ordinals NFT 都不进入聪网。Agent 将这些未指定资产排除在 L2 余额守恒预期之外。
Agent 只提供资产名和金额，不要求用户指定 splicing-in 的资产输入。adapter 内部选币默认避开多资产 UTXO；如果必须使用，需要在预览里说明哪些资产会 ascend、哪些资产会被忽略。
协议资产 splicing-out 剧本
Runes、BRC20、ORDX 等协议资产从通道退出到 BTC L1 时，Agent 应按以下顺序执行：
运行
stp.safety_snapshot，确认通道是READY_SAFE。查询本地和 Core Node 的
commitHeight、chanPoint、资产余额，确认双方一致。发起协议资产
stp.splicing_out，只传资产、金额和目标 BTC 地址；资产输入、transfer inscription 和 fee 输入都由 adapter 内部处理。如果 adapter 返回 fee 不足或资产输入不可构造，停止并按错误提示补充资金或等待资产状态收敛，不手工传入 UTXO。
记录 reservation、L2 deAnchor tx、L1 splicing-out tx，以及可能的 commit/reveal 前置 tx。
先确认聪网 deAnchor 是否完成，再异步轮询 BTC L1 splicing-out tx 确认。
操作完成后再次运行
stp.safety_snapshot，确认 commit height 前进、承诺交易更新、旧 remote commitment 已有 punish coverage。
如果第 3 步返回 timeout、连接中断或未知网络结果，Agent 不得立即重发。应进入“未知网络结果后判断是否可重试”工作流，先比较双方通道状态、reservation 和 L1/L2 tx 可见性。
客户端操作参考
以下是 Agent 应使用的高层 STP 客户端操作。具体可以由本地服务、SDK、命令行工具或独立客户端库提供，协议不限定开发语言和传输方式。
创建钱包
钱包创建请求
钱包 ID、助记词、地址
创建后应进入可初始化状态
导入钱包
钱包导入请求
钱包 ID、地址
导入后应进入可初始化状态
解锁钱包
钱包解锁请求
钱包 ID、地址
解锁后才能签名
打开通道
通道打开请求
通道 ID
初始容量通常为白聪
关闭通道
通道关闭请求
关闭交易 ID、退出交易 ID
可协商关闭或强制关闭
Unlock
通道释放请求
交易 ID、事务 ID
通道到聪网个人地址
Lock
通道回锁请求
交易 ID、事务 ID
聪网个人地址到通道
Lock With Expand
回锁扩容请求
交易 ID、事务 ID
通道容量不足时恢复资产通道控制权
Splicing-In
通道扩入请求
交易 ID、事务 ID
L1 资产进入通道
Splicing-Out
通道扩出请求
交易 ID、事务 ID
通道资产退出到 L1
Expand
通道纳管请求
anchor 交易 ID、金额
已在通道地址的资产纳入管理
Expand All
批量纳管请求
anchor 交易 ID 列表、金额
批量纳入资产
Deploy Runes
Runes 部署请求
交易 ID、事务 ID、动作结果
远端长耗时动作
查询通道
通道状态查询
channel detail
只读查询接口
查询 reservation
reservation 状态查询
status/result
只读查询接口
请求字段规范
通道打开请求
feePolicy
可选 L1 费用策略；adapter 可忽略并使用内部估算
amt
初始通道金额，单位聪
memo
可选备注
通道扩入请求
channel
通道 ID
assetName
资产名，如白聪、ORDX、Runes、BRC20 表达
amt
字符串金额，必须符合资产 divisibility
feePolicy
可选 L1 费用策略；adapter 可忽略并使用内部估算
reason
操作原因，用于上层流程关联
Agent-facing adapter 不暴露底层资产输入或手续费输入参数。资产输入、BRC20 transfer inscription 和手续费输入都由 adapter 内部选择或构造。
通道扩出请求
channel
通道 ID
address
BTC L1 目标地址
assetName
资产名
amt
字符串金额
feePolicy
可选 L1 费用策略；adapter 可忽略并使用内部估算
reason
操作原因
more
额外数据，用于上层流程关联
通道扩出前置检查：
查询通道状态，必须为 ready。
查询本地和 Core Node 的
commitHeight、chanPoint，必须一致。Agent 不传 fee 输入。adapter 内部选择纯白聪 fee 输入；如果不足，返回明确错误和补充资金建议。
若资产是 BRC20，transfer 输出选择或铸造由 adapter 内部完成。
通道释放请求
channel
通道 ID
assetName
资产名
amt
字符串金额
address
聪网目标地址，空值时默认当前钱包地址
Agent-facing adapter 不暴露 unlock 输入或 fee 输入参数。adapter 在通道内自动选择可用输入，并处理聪网手续费。
通道回锁请求
channel
通道 ID
assetName
资产名
amt
字符串金额
Agent-facing adapter 不暴露 lock 输入或 fee 输入参数。adapter 在用户聪网地址上自动选择资产输入和手续费输入；容量不足时返回 INSUFFICIENT_CHANNEL_CAPACITY 并建议 lock-with-expand。
状态追踪
Agent 持续查询 reservation 和链上状态，而不是只看发起接口是否返回成功。
推荐规则：
返回
resvId时，以resvId为主跟踪。返回
txId但没有resvId时，以链上确认和 wallet action status 为主跟踪。RS_CONFIRMED表示协议动作达到确认状态。RS_CLOSED表示 reservation 生命周期关闭，不一定表示通道关闭。RS_FAILED或RS_REMOTE_FAILED必须停止自动推进，并把错误暴露给用户。CS_READY是大多数通道动作的前置状态。CS_CLOSE_FORCELY_*期间停止发起新的普通通道动作。
聪网 UTXO 规则：
聪网 L2 UTXO 没有 BTC dust 限制，可以为 0。
BRC20 和 Runes 在 L2 不需要绑定聪，因此一个聪网 UTXO 可以携带 BRC20 或 Runes 资产，同时聪数量为 0。
在 BTC L1 上，携带 BRC20/Runes 转移资产的 UTXO 仍然受 L1 输出限制，当前通常使用最小的 330 sats。
ORDX 必然绑定聪；Agent 必须根据资产数量和
bindingSat参数计算需要多少聪，不能套用 BRC20/Runes 的 0-sat UTXO 规则。对白聪 unlock，Agent 只指定释放金额；adapter 必须在通道内选择足以覆盖
unlock amount + SatoshiNet fee的输入。对白聪 lock，
amount是回锁进通道的净金额；钱包输入还需要额外覆盖 SatoshiNet fee。Agent 以聪网交易验证和资产守恒为准，不因为聪网找零小于 330 sats 就判断交易非法。
安全护栏
Agent 必须遵守以下限制：
不自动执行 mainnet 高价值转移，除非用户明确确认资产、金额、地址、fee rate 和操作类型。
不在
channel is busy时并发发起同一通道的新动作。不复用已有未完成 reservation 的 UTXO。
不在 peer offline 时启动需要协作签名的普通动作；强制关闭除外。
不手写底层协商消息，除非具备完整签名、commitment、revocation 构造能力。
BRC20 操作必须提示可能产生 commit/reveal 前置交易，且耗时更长。
Runes deploy 需要等待 commit tx 超过确认阈值后再 reveal，不能按普通单交易处理。
所有目标地址必须按网络校验，避免 testnet/mainnet 混用。
典型 Agent 工作流
工作流 A：首次进入聪网
查询钱包是否解锁。
查询节点和 indexer 是否 ready。
查询是否已有 ready 通道。
没有通道时调用 open channel。
轮询通道状态直到
CS_READY。对目标资产调用 splicing-in。
轮询 reservation 到确认。
如果用户要在聪网自由使用资产，调用 unlock。
输出最终 L1 tx、L2 tx、通道 ID、reservation ID 和资产位置。
工作流 B：从聪网退回 BTC L1
确认目标 BTC 地址网络正确。
判断资产在通道中还是聪网个人地址。
在通道中：调用 splicing-out。
在个人地址：先调用 lock；容量不足时调用 lock-with-expand，然后再 splicing-out。
如果 adapter 报告协议资产 splicing-out 的 BTC L1 fee 资金不足，提示用户补充普通 BTC fee 资金或等待资金确认，不让 Agent 手工指定 fee 输入。
轮询聪网退出状态。
轮询 L1 tx 确认。
输出最终 L1 txid 和剩余通道状态。
工作流 D：未知网络结果后判断是否可重试
记录失败操作、请求摘要、错误文本、channel id、asset、amount。
查询本地 reservation；若存在 pending reservation，不重试，继续轮询原事务。
查询 Core Node 端 channel 和 reservation。
查询相关 L1/L2 tx 是否可见。
若任一方
commitHeight或chanPoint已变化，或任一 tx 可见，进入跟踪/恢复流程，不重试原操作。只有在双方仍处于同一 ready 状态、无 pending reservation、无相关 tx 可见时，才允许重新做 preflight，由 adapter 重新选择输入并重试。
对早期协商阶段的未知网络结果，也必须执行上述比较；不能只因为“尚未广播”就直接重试。
工作流 C：恢复未完成操作
查询 adapter 返回的 reservation 列表。
找出非
RS_CLOSED、非RS_CONFIRMED、非失败状态的 reservation。按类型分类：open、splicing、payment、remoteaction、localaction。
查询关联 tx 是否已确认。
等待钱包或 STP 服务继续推进；只在 adapter 明确要求时执行恢复动作。
若 peer 已无法识别该 reservation，停止自动操作并提示用户确认链上资产位置。
Agent 输出格式建议
每次操作完成或暂停时，Agent 应输出：
intent
用户目标
network
mainnet/testnet
asset
资产名和金额
from / to
资产迁移方向
channelId
相关通道
txIds
已广播交易
resvId
reservation id
currentStatus
当前 channel/reservation 状态
nextCheck
下一步应查询的对象
risk
是否需要用户确认或人工介入
与 SAT20 Agent Wallet 的关系
sat20-agent-wallet 是本文规范的可安装形态。它把 Agent 能力拆成三个权限层次：
只读查询：查询钱包、通道、reservation、余额、资产位置和安全快照。
测试网操作：允许 testnet 自动 open、splicing、unlock、lock、lock-with-expand、splicing-out 和 punish drill。
主网计划：mainnet 操作默认先生成计划和风险清单，执行前要求用户逐项确认。
这三个层次共享同一套状态模型，但权限和确认策略不同。这样既能让 Agent 真正操作 STP，又能避免在主网上出现不可逆误操作。
Last updated