POC 机制、合约与架构白皮书
POC 是 Topo 生态中的贡献到 power 机制。它把 DApp 内发生的真实用户贡献，通过链上可信事件、Coinfair 价格快照、周期结算和链上 PowerStore，转化为可读取、可审计、可组合的用户 power。
本文面向技术评审方、DApp 开发者、治理参与方和生态合作方，解释 POC 为什么不是普通积分系统，链下结算如何保持可审计，以及链上最终承诺如何被下游模块读取。
核心结论
- POC 的输入是链上可信 ContributionEvent，不是 DApp 自行上报的普通日志。
- POC 的价值归一化来自 Coinfair 的周期价格快照，而不是事后实时价格。
- POC 的计算在链下完成，原因是多 App、多用户、多价格和历史状态的周期聚合不适合逐笔放在链上。
- POC 的最终结果必须写回链上 PowerStore，链上应用只读取 committed power。
- POC 的可信性来自链上可信输入、链下可回放计算、链上最终承诺和写回后对账四个环节。
POC 要解决的问题
很多链上权重模型主要来自资产或 stake。这类模型容易表达资本投入，但很难表达用户在 DApp 中产生的真实业务贡献。
对 DApp 来说，贡献可能表现为交易、创作、参与、流动性、消费、任务完成或其他业务行为。不同 App 的贡献口径不同，token 价值不同，用户贡献也发生在不同时间。POC 需要把这些异构贡献转化成统一的链上 power。
POC 的目标不是替代 DApp 的业务逻辑，而是提供一个统一的贡献清算和链上权重承诺层。
一句话机制
完整链路可以拆成七步：
- 用户在 DApp 中产生业务贡献。
- DApp 通过 POC 可信路径发放 equity token。
- POC 合约在校验 App、token、custody 后发出 ContributionEvent。
- 计算层按周期收集可信事件，并获取 Coinfair 价格快照。
- 计算层结合 App 权重、用户贡献占比和历史 power 衰减，计算用户最终 power。
- 写回服务将结果写入链上 PowerStore 的下一周期 staged power。
- 链上周期推进后，staged power 变成 committed power，供下游模块读取。
三层架构
POC 可以抽象为链上可信层、链下计算层和链上消费层。
| 层 | 职责 | 不承担 |
|---|---|---|
| 链上可信层 | App 准入、可信贡献事件、PowerStore 最终承诺 | 多 App 大规模聚合计算 |
| 链下计算层 | 周期聚合、价格快照、历史状态处理、批量写回 | 自行制造贡献输入或覆盖链上最终结果 |
| 链上消费层 | 读取 committed power 并用于 staking、governance、reward 等模块 | 重新解释 DApp 贡献口径 |
链上合约边界
poc_registry
poc_registry 是 App 准入、身份和权重中心。它至少需要表达：
| 能力 | 说明 |
|---|---|
| App 身份 | 记录 app address、app id、状态和基础 metadata |
| token 绑定 | 记录 DApp equity token 与 custody 的对应关系 |
| 权重治理 | 管理 App 权重、生效周期和暂停状态 |
| 准入状态 | 标识 App 是否可产生 POC 认可的贡献事件 |
| 审计事件 | 对 App 注册、暂停、恢复、权重变更和 token 绑定发出事件 |
Registry 的核心作用是让贡献事件有可验证来源和可治理权重。没有 Registry 准入的 App，不应进入 POC 结算。
poc_contribution
poc_contribution 是可信贡献事件入口。它不负责计算最终 power，而是负责校验并发出 POC 认可的 ContributionEvent。
ContributionEvent 的可信性来自：
- 调用方必须来自已准入的 DApp 或授权模块。
- equity token 和 custody 必须与 Registry 记录匹配。
- token 发放和事件输出在同一可信路径内完成。
- 事件包含 app、beneficiary、token、amount、period 归属线索和版本信息。
- 消费者可以回链上验证事件来源和 App 状态。
poc_power_store
poc_power_store 是链上 power 账本。它保存周期化的 staged power 和 committed power，并为下游模块提供统一读取口径。
PowerStore 的关键规则：
- Writer 只能写入下一周期 staged power。
- 当前周期 committed power 不应被逐笔实时修改。
- 周期边界后，staged power 才成为新的 committed power。
- 历史状态保留和衰减规则应可审计。
- 下游模块只读取 committed power。
价格与周期结算
POC 需要把不同 App、不同 equity token 和不同贡献时间的输入归一化。周期结算通常需要以下输入：
| 输入 | 来源 | 作用 |
|---|---|---|
| ContributionEvent | poc_contribution | 表示可信贡献发生 |
| App 权重 | poc_registry | 表示 App 在当前周期的治理权重 |
| token 价格 | Coinfair 周期快照 | 把不同 equity token 转换为统一价值口径 |
| 历史 power | poc_power_store | 支持继承、衰减或其他历史状态规则 |
| 周期参数 | 链上配置和结算配置 | 决定归属周期、写回窗口和生效边界 |
概念计算可以理解为：
App 周期价值 = App 周期贡献数量 × equity token 周期价格 × App 权重
用户贡献占比 = 用户周期贡献数量 / App 周期总贡献数量
用户增量 power = App 周期价值 × 用户贡献占比
用户最终 power = 历史 power 处理结果 + 用户增量 power
真实系统应使用固定精度、明确快照、确定性排序、可重放账本和链上写回校验。文档中的公式只用于说明机制，不代表具体实现中的全部参数。
信任边界
| 环节 | 信任来源 | 风险控制 |
|---|---|---|
| DApp 业务事实 | DApp Move 合约状态机和事件 | 状态机、权限、资产校验、事件版本 |
| ContributionEvent | poc_contribution 和 Registry 校验 | App 准入、token/custody 匹配、重复发放保护 |
| 价格快照 | Coinfair 周期价格来源 | 固定周期、快照记录、异常 hold |
| 链下结算 | 可回放输入、确定性计算、结算账本 | 输入归档、版本化算法、对账报表 |
| 写回 | Writer 权限和 PowerStore 校验 | 只写下一周期、批次记录、失败重试 |
| 下游消费 | PowerStore committed power | 不读取 staged power，不读取本地预估值 |
POC 允许链下做复杂计算，但不允许链下系统自行创造可信输入或覆盖最终链上承诺。
审计与恢复
POC 运行中需要支持以下审计链路：
wallet address
-> DApp business object
-> DApp chain event
-> ContributionEvent
-> POC period
-> price snapshot
-> settlement ledger
-> staged power writeback
-> committed power
常见异常和处理方向：
| 异常 | 处理原则 |
|---|---|
| ContributionEvent 摄入失败 | 从链上事件重新扫描，按 event id 或 tx hash 幂等处理 |
| 价格快照失败 | 当前周期进入 hold，不使用临时人工价格覆盖 |
| 结算任务失败 | 保留输入和错误上下文，修复后重放同一周期 |
| Writer 写回失败 | 记录批次状态，重试写入下一周期 staged power |
| App 被暂停 | 停止新贡献进入结算，历史 committed power 按治理规则处理 |
| 争议或作弊 | 通过后续贡献抵扣、治理修正或专门 reversal 机制处理 |
FAQ
DApp 能否自己发贡献事件？
DApp 可以发出自己的业务事件，但 POC 只认可可信路径产生的 ContributionEvent。普通业务事件可以作为候选贡献、审计材料或读模型输入，不能直接成为 POC power。
为什么贡献不是实时变成 power？
POC 需要同时处理多 App、多 token、价格快照、App 权重和历史状态。逐笔实时修改 power 会让价格、周期和审计边界变得不稳定，因此 POC 使用周期结算和下一周期写回模型。
为什么价格变化后历史结算不重算？
周期快照的意义是为当前周期提供确定口径。历史周期如果随价格波动反复重算，会破坏可审计性和下游依赖的稳定性。
如果 App 被暂停会怎样？
暂停后的新贡献不应继续进入 POC 结算。已经生效的 committed power 如何处理，应由治理规则、风险等级和修正机制决定。
下游模块应该读 staged power 还是 committed power？
下游模块只应读取 committed power。staged power 是下一周期的待生效结果，用于写回、对账和周期推进前的准备。
术语表
| 术语 | 含义 |
|---|---|
| POC | 把 DApp 可信贡献转化为链上 power 的周期性清算机制 |
| App 权重 | Registry 中用于调节 DApp 贡献影响力的治理参数 |
| equity token | DApp 用于表达贡献或权益的资产载体 |
| ContributionEvent | POC 认可的链上可信贡献事件 |
| staged power | 已写入但尚未生效的下一周期 power |
| committed power | 当前周期已生效、可被下游读取的 power |
| PowerStore | 保存 staged power 和 committed power 的链上账本 |
| period | POC 结算周期 |
| Writer | 将结算结果写回 PowerStore 的服务或授权执行方 |
总结
POC 的核心不是把所有计算放到链上，而是把可信输入和最终承诺放在链上，把复杂、可回放、可审计的聚合计算放在链下。只要 ContributionEvent、价格快照、结算账本、写回批次和 PowerStore 之间可以完整对账，POC 就能在性能和可信性之间保持清晰边界。