DApp 接入参考案例
1. 案例定位
本附录以交易型 DApp 为例说明 POC V2 的接入方式。案例只界定安全边界，不要求所有 DApp 使用相同的业务状态机。游戏、内容、任务、去中心化金融（DeFi）和供应链应用可以分别定义成熟条件，但 候选活动、成熟事实、可信发行 与 已激活算力（Activated Power） 四个阶段必须彼此独立。
2. 成熟贡献
支付、点击、订单创建或前端显示成功都只是候选活动。业务状态机排除主要撤销路径，或进入明确且可治理的后续纠错阶段后，贡献才算成熟。
| 事实类别 | 交易型 DApp 示例 | POC 处理 |
|---|---|---|
| 候选活动 | 下单、支付、锁定库存 | 不产生 POC 算力 |
| 成熟条件 | 履约确认、服务验收、锁定期结束 | 允许进入贡献发行判断 |
| 成熟贡献 | 结算已执行、净值已确定 | 可以通过可信路径发行 |
| 退款或争议 | 退款、仲裁、欺诈、拒付 | 取消、冻结、未来抵扣或治理纠正 |
3. 参考旅程
接入流程分为八步：
- 用户通过钱包签署业务交易。
- 合约执行支付、资产锁定或订单状态转换。
- 履约、验收、锁定期和结算规则形成成熟事实。
- DApp 的贡献管理模块（contribution manager）检查成熟状态、幂等性、暂停状态、受益人和托管关系。
- DApp 通过 POC 可信贡献入口（poc_contribution）发放权益代币并产生贡献事件（ContributionEvent）。
- 事件达到最终确认后，进入验证者（Validator）的下一次计算范围。
- POC V2 完成独立复算、投票与 QC、候选结果、交付批次、封存和原子激活。
- DApp 前端或下游模块通过算力读取模型（PowerReadModel）读取已激活算力。
4. 注册表与权益代币
DApp 接入前必须在注册表（Registry）中登记以下信息：
- 应用管理权限和链上地址；
- DApp 权益代币；
- 托管地址；
- POC 准入与暂停状态；
- 有效权重及其周期语义；
- Topo DEX 的基础代币与报价代币价格对（base_token / quote_token）。
权益代币是可信贡献路径中的价值载体和价格身份，不等同于最终算力。只有贡献事件进入确定性周期计算并最终激活后，用户才能获得协议可读算力。
5. Topo DEX 价格接入
DApp 必须为权益代币配置可审计的 Topo DEX 价格身份。POC 使用的是计算上下文（Context）价格读取边界（price_read_fence）上的最新稳定价格，而不是 DApp 后台报价、当前周期临时价格或贡献发生周期的专属价格。
接入验收需要确认：
- 价格源已经注册，且报告方授权正确；
- 已形成至少一条稳定价格和价格更新事件（PriceUpdatedEvent）；
- 注册表中的价格身份映射明确；
- 未形成稳定价格时任务会弃权（Abstain），不会使用默认值；
- 前端和运维界面能够显示价格陈旧程度，但不能自行替换价格。
6. 业务交易入口
钱包签名交易的后端入口必须验证：
| 检查项 | 要求 |
|---|---|
| 身份 | 交易发送方与已认证钱包一致，链 ID 正确 |
| 目标 | 合约地址、模块、函数和泛型参数在允许列表中 |
| 语义 | 订单、资产、数量、受益人和业务状态与服务端事实一致 |
| 幂等 | 交易哈希、业务对象和重试具有明确唯一键 |
| 结果 | RPC 接受不等于成功，最终状态以最终确认的链上事实为准 |
后端不应只是转发已签名交易对象（signedTx），也不能把本地数据库状态当作链上执行成功的证明。
7. 合约职责
交易型 DApp 的 Move 合约应清晰分离：
- 业务状态机与权限；
- 资产、库存、托管与退款；
- 结算和成熟条件；
- 贡献管理模块；
- 对外事件与只读视图（view）。
贡献事件必须由 POC 可信贡献入口产生。DApp 自己的业务事件可以作为审计证据，但不能替代 POC 输入。
8. 业务结算与 POC 解耦
贡献发行或后续 POC 链上交付失败，不得阻塞商户资金结算。业务状态机应先完成合法的资金与权益处理，再把符合条件的成熟事实提交贡献发行。
| 场景 | 业务结果 | POC 结果 |
|---|---|---|
| 结算成功、贡献发行成功 | 商户结算完成 | 产生贡献事件 |
| 结算成功、贡献发行暂时失败 | 商户结算仍完成 | 记录可重试或暂缓状态，不伪造事件 |
| 结算前退款或争议 | 退款、仲裁或取消 | 不发行贡献 |
| 发行后争议 | 业务按治理规则纠正 | 通过未来抵扣、反向贡献或治理机制处理 |
| 应用暂停 | 已有业务按安全规则完成 | 停止新的贡献发行 |
9. 事件投影与用户界面
事件消费器（Event consumer）只投影最终确认的链上事实，并支持幂等、重放、缺口检测和对账。用户界面应分别显示：
- 业务交易已提交；
- 链上业务事实已确认；
- 贡献已经成熟；
- 贡献事件已产生；
- 已进入 POC 计算范围；
- 候选结果尚未激活；
- 已激活算力已经可以读取。
将这些状态合并成一个“奖励成功”会掩盖最终确认、未达法定权重（NoQuorum）和自动追赶边界。
10. 接入步骤
| 阶段 | 主要产出 | 退出条件 |
|---|---|---|
| I0 业务语义 | 状态机、成熟条件、退款和争议规则 | 产品、合约、后端和测试定义一致 |
| I1 链上事实 | Move 合约、事件、只读视图、权限和初始化 | 关键路径与负向测试通过 |
| I2 POC 身份 | 注册表、权益代币、托管关系、权重和价格身份 | 所有状态可查询并可审计 |
| I3 可信发行 | 贡献管理模块与 POC 可信贡献入口 | 成熟、重复、暂停和余额测试通过 |
| I4 投影与对账 | 事件消费器、读取模型和对账机制 | 可从链重放并修复 |
| I5 影子接入 | 观察贡献、计算上下文与验证者结果 | 多周期输入一致，不写入生产算力 |
| I6 受控启用 | 测试网强制执行与有限生产试点 | 安全阶段门槛、监控和故障演练通过 |
11. 接入验收
- 候选活动和成熟贡献有不同的链上状态。
- 支付成功不会直接产生算力。
- 贡献事件只能从 POC 可信路径产生。
- 注册表中的应用、代币、托管关系、状态、权重和价格身份一致。
- POC 故障不会阻塞合法的业务资金结算。
- 退款、争议、暂停和发行后纠正路径有明确状态与审计事件。
- 事件消费器可以从最终确认的链上事实重放，不依赖不可验证的本地日志。
- 前端清楚区分贡献发行、候选结果处理和算力激活。