Topo 链 DApp 生态合作与 POC 接入白皮书
本文面向生态合作方、业务方、DApp 团队和技术负责人，说明 Topo 链上的 DApp 如何形成可信业务闭环，DApp 贡献如何进入 POC 体系，以及合作接入时需要准备和验收的关键事项。
本文只表达对外合作、业务事实流、可信关系和接入边界；具体合约模块、后端入口和事件消费者实现请继续阅读开发者架构指南。
执行摘要
Topo 链上的 DApp 不只是“前端连接钱包、合约记录交易”的应用。一个成熟的 Topo DApp 应形成清晰的可信闭环：
- 用户在 DApp 中产生真实业务行为。
- 影响资产、权限、状态和贡献的关键事实由链上合约保护。
- 链上事件成为审计、对账和生态协作的共同事实。
- 链下服务负责体验、查询、风控、运营和对账，但不替代链上事实。
- 如果 DApp 接入 POC，只有经过可信路径产生的贡献事件才会进入周期结算。
- POC 结算结果最终写入 PowerStore，成为生态中可读取、可审计、可组合的权重。
对合作方而言，Topo DApp 的价值在于：业务可以保留高效的产品体验，同时把真实交易、履约、参与、供给、增长等贡献转化为链上可信资产和可组合权重。
核心概念
| 概念 | 对外解释 |
|---|---|
| Topo 链 | 承载 DApp 资产、权限、状态机和可信事件的链上基础设施 |
| DApp | 在 Topo 链上运行核心可信逻辑的业务应用 |
| Move 合约 | 保护资产、状态和权限的链上程序 |
| 链上事件 | DApp 对外公开的可信业务事实，可用于同步、审计和对账 |
| 读模型 | 面向用户体验和运营查询的链下数据视图，可异步更新 |
| equity token | DApp 用于表达贡献或权益的资产载体 |
| POC | 把 DApp 可信贡献转换为链上 power 的周期性清算机制 |
| ContributionEvent | POC 认可的可信贡献事件，不是 DApp 自行上报的普通记录 |
| PowerStore | 链上保存 POC power 的账本，下游只读取已生效的 committed power |
| staged power | 已写入链上但尚未生效的下一周期 power |
| committed power | 当前周期已生效、可被下游读取的 power |
| Coinfair 价格快照 | POC 结算中用于价值归一化的周期价格来源 |
Topo DApp 的可信闭环
Topo DApp 的设计重点是把用户行为、链上事实、可信贡献和生态权重连接起来。
这个闭环的关键不是“所有数据上链”，而是让决定资产、权重、权限、结算和生态协作的事实拥有统一可信来源。图片、富文本、复杂搜索、运营报表、推荐排序和可由链上事实重建的展示数据，通常更适合放在链下系统中。
核心设计原则
链上保护关键事实
Topo DApp 应把影响资产、权重、权限和结算的关键事实放到链上，例如：
- 资产托管、支付、退款、结算和提现。
- 业务对象的核心生命周期。
- 角色、权限、暂停和高风险参数。
- 可审计、可回放的业务事件。
- 可计入 POC 的成熟贡献事实。
链下服务提升体验
链下服务可以负责登录、交易构造、风控校验、查询聚合、运营审核、通知、搜索和数据分析。但链下服务不能覆盖链上资产和状态事实。
| 能力 | 推荐位置 | 原因 |
|---|---|---|
| 资产转移 | 链上合约 | 必须可信、原子、可审计 |
| 权限和高风险参数 | 链上合约 | 防止中心化系统单点篡改 |
| 复杂查询和运营报表 | 链下读模型 | 成本低、体验好、可扩展 |
| 搜索和筛选 | 链下索引 | 不适合占用链上存储和计算 |
| 贡献到 power 的最终结果 | PowerStore | 下游模块需要链上统一口径 |
POC power 只来自 PowerStore
本地积分、营销分、普通业务事件和预估贡献都不能直接等同于 POC power。POC power 需要经过可信贡献、价格快照、周期结算和链上写回，最终以 PowerStore 中的 committed power 为准。
前端和业务材料中应区分四类状态：
- 已产生业务行为。
- 已形成成熟贡献。
- 已进入 POC 周期结算或已写入 staged power。
- 已成为 committed power。
推荐总架构
POC 贡献到 power 的链路
POC 的接入不是让 DApp 直接上报积分或 power，而是让 DApp 通过可信路径把成熟贡献转化为 ContributionEvent，再由 POC 结算层统一处理。
DApp 成熟贡献事实
-> DApp contribution_manager 校验和发放
-> poc_contribution 产生 ContributionEvent
-> POC Engine 按周期收集事件
-> Coinfair 价格快照和 Registry 权重归一化
-> POC Writer 写入下一周期 staged power
-> 周期边界后成为 committed power
关键规则：
- DApp 必须先在 Registry 中完成 app、equity token、custody 和权重配置。
- ContributionEvent 必须由 POC 可信贡献路径产生。
- 价格快照、App 权重和周期归属必须在结算时有明确口径。
- Writer 只写下一周期 staged power。
- 下游模块只读取 committed power。
DApp 接入视角
合作方在接入 Topo 和 POC 前，需要先把业务事实拆清楚。
| 准备项 | 说明 |
|---|---|
| 业务对象 | 哪些对象需要链上状态机，例如订单、任务、仓单、权益、凭证或结算单 |
| 资产口径 | 哪些资产需要托管、支付、退款、结算或发放 |
| 成熟贡献 | 哪些业务结果可以被认为已经成熟，且可以进入 POC 贡献路径 |
| 异常路径 | 退款、撤销、仲裁、作弊、暂停和治理修正如何处理 |
| equity token | DApp 用于表达贡献或权益的 token，以及对应 custody 方案 |
| 价格来源 | equity token 是否具备可用于周期快照的 Coinfair 市场 |
| 权重治理 | App 是否进入 POC 白名单，以及初始权重和调整规则 |
| 对账链路 | 能否从用户地址追踪到业务对象、链上事件、ContributionEvent 和 PowerStore |
推荐接入顺序
| 阶段 | 目标 | 主要产物 |
|---|---|---|
| 业务建模 | 明确链上事实、链下体验和成熟贡献口径 | 状态机、事件清单、贡献规则 |
| 合约设计 | 把资产、权限、状态和可信事件放入 Move 合约 | DApp 合约包、初始化脚本、view |
| 入口治理 | 建立钱包登录、signed transaction 校验和幂等 | API 到 ABI 清单、tx log、风控配置 |
| 事件同步 | 建立读模型、搜索投影和对账能力 | 消费者、读模型、重放和修复工具 |
| POC 准入 | 完成 Registry、equity token、custody 和价格来源 | App 注册、token 配置、权重配置 |
| 贡献发放 | 将成熟贡献接入 POC 可信贡献路径 | contribution_manager、ContributionEvent 对账 |
| 灰度上线 | 验证周期结算、staged power 和 committed power | 监控指标、对账报表、异常处理流程 |
对外验收清单
- DApp 的链上状态机、资产流和权限边界已经明确。
- 关键业务事件可以从链上重放和审计。
- 链下读模型不会覆盖链上资产和状态事实。
- DApp 已定义成熟贡献口径，且与支付成功、本地积分和普通日志区分清楚。
- equity token、custody、Registry 权重和价格来源已经确认。
- ContributionEvent 到 POC 周期账本、staged power 和 committed power 可对账。
- 退款、争议、暂停、恢复和治理修正路径已定义。
- 上线前已完成安全、测试、可观测性和对账验收。
总结
Topo DApp 的对外合作核心，是把真实业务行为转化为链上可验证事实，并通过 POC 把成熟贡献转化为可读取、可审计、可组合的 committed power。
生态合作方不需要把全部业务迁移到链上，但必须守住三条边界：链上保护关键事实，链下服务只增强体验，POC power 只来自可信贡献和 PowerStore 最终承诺。