跳轉到

D-20260811-16｜經濟月流水與創作者收益衍生讀模型

背景與驅動力

月流水與創作者累計 royalty 原由 provider 每當 log heads 變化時掃描全部原始事件。這條路徑繞過 reducer 的有效性判定，可能把餘額不足、重複結算或其他 no-op 事件納入 UI；checkpoint 覆蓋後 raw entry 可合法淘汰，新 peer 也無法靠全史掃描重建。即使以 log head memo 降低重複成本，仍沒有解決資料正確性與 checkpoint 自含性。

考慮過的選項

  • 保留 raw-log 掃描並強化 memo：改善平均效能，但無法證明事件真的被 fold 接受，也不適用於 checkpoint 後淘汰的歷史，棄。
  • 僅把 rolling 月流水寫入 state，創作者 lifetime 收益仍掃 log：留下同一類正確性缺口，且讀取成本會隨全史成長，棄。
  • 同時建立 rolling 月流水與 lifetime royalty 累計投影，由 reducer 維護並納入 checkpoint（採納）。

決定

  • EconomyDerivedState 新增 monthlyFlowsByMonth 與 lifetimeRoyaltyMintedByPeer。月流水按 UTC YYYY-MM 及 peer 存 minted／burned bigint；lifetime 只存每 peer 實際鑄出的 royalty 總額，不含 match prize 或 sponsor burn。
  • 只有通過全部共識守門、真正改變 state 的 upload、slot purchase、maintenance、sponsor 與 match settlement 才更新投影。拒絕／no-op 事件不留任何流水。
  • 月流水保留當月含往前 11 個 UTC 月；ECONOMY_MONTHLY_FLOW_RETENTION_MONTHS = 12 為 protocol 常數，append 與 checkpoint GC 共用同一裁剪邏輯。過期遲到事件不重建已淘汰月份。lifetime royalty 不 GC。
  • 兩欄納入 canonical DerivedState codec、CID 與 checkpoint 驗證；金額往返一律以 bigint 處理。本專案尚未對外發布，不提供缺欄的舊 checkpoint fallback，decode 直接 fail-closed 並由全史 refold 產生新 checkpoint。
  • EconomyData.monthlyFlows 與 creator profile 直接讀投影，移除 getAllEvents()、log-head memo 與 provider 端費率重播。

後果與影響

UI 與 checkpoint/refold 的經濟數字來自同一個共識投影，不會把偽造或 no-op 事件誤當成流水；原始事件被 checkpoint coverage 安全淘汰後，讀點仍完整。代價是 derived state 多一份有界 12 月稀疏 map 與一份每 peer 的永久 bigint；但查詢從 O(events) 降為 O(12)，且不再需要依 log heads 管理 cache invalidation。