结算与审计

1) 我们为什么要这样做？

• 透明性：将一个计费周期内所有可计费用量和价格冻结为快照，以便任何一方都能独立验证。

• 可验证性：每一行条目（包括分段路由）都有哈希；全部条目汇总为一个默克尔根；快照被签名。

• 可追溯性：在发生争议时，您可以钻取到确切的请求记录及其金额。

---

2) 计费周期与产物

• 周期：每周。

• 产物（至少包括）：

  • snapshot.json – 包含该周期内所有成功调用记录的默克尔根以及该时期价格表的链接。

    • 示例键：

      • merkleRoot：针对所有成功使用记录计算的默克尔根。

      • priceUrl：用于获取本周期生效价格表的 URL。

---

3) 快照结构

3.1 快照模式（示例）

{
  "epoch": 1234,
  "merkleRoot": "0xabc...",
  "priceUrl": "https://proxy.anyint.io/priceUrl/"
}

3.2 子集导出（对用户/提供方私有）

按账户提供导出（例如 my-records.jsonl / CSV）。字段名可能包括 requestId、model、tokenIn、tokenOut、proof 等。

• 如果存在证明，您可以验证每条记录是否包含在默克尔根中。

• 没有证明时，您仍可重新计算金额并对账总额，但无法独立证明记录的包含性。

3.3 默克尔构造与证明

• 叶子：对每个规范化记录的规范 JSON 计算 keccak256。

• 排序：按哈希（升序）对叶子进行排序以形成叶序列。

• 树：二叉默克尔；若某一层叶子数量为奇数，则复制最后一个叶子以凑成一对。

  内部节点：H = keccak256(left || right)。

• 根：将生成的 merkleRoot 写入 snapshot.json。

• 证明（可选）：可以提供 proofs.jsonl：

{ "recordId": "...", "leaf": "0x...", "proof": ["0x...", "..."] }

• 可用其验证叶子 → merkleRoot 的包含关系。

---

4) 价格表与单位

• 货币与精度：以美元为锚，通常保留 6 位小数。

• 单位：per_1k_tokens（每 1,000 个标记的价格）。

• 结构（示例）：

"priceTable": [
  {
    "epoch": 1234,
    "model": "gpt-4o",
    "priceIn":   0.005,  // 输入的费用价（USD / 1k tokens）
    "priceOut":  0.015,  // 输出的费用价（USD / 1k tokens）
    "rewardIn":  0.004,  // 输入的奖励价（USD / 1k tokens）
    "rewardOut": 0.013,  // 输出的奖励价（USD / 1k tokens）
    "currency": "USD",
    "unit": "per_1k_tokens"
  }
]

含义

• price* → 用于向用户计费的基准费用价格。

• reward* → 用于向提供方支付的基准奖励价格。

---

5) 金额公式（如已实现）

用户费用

userCostUSD = (priceIn  * Tin / 1000) + (priceOut  * Tout / 1000)

提供方奖励

providerRewardUSD = (rewardIn * Tin / 1000) + (rewardOut * Tout / 1000)

精度与取整

• 对货币值使用定点小数（例如带 6 位小数的 Decimal）。

• 标记计数为整数；金额以 6 位小数的 USD 存储/四舍五入。

---

6) 本地自我验证（离线）

6.1 步骤

1. 获取快照：下载该周期的 snapshot.json 以获取 epoch、merkleRoot 和 priceUrl。

2. 获取价格表：通过 priceUrl 检索该 epoch 的 priceTable。

3. 导出您的子集：从控制台导出相关记录（例如 my-records.jsonl / CSV）。

4. 验证默克尔包含性（若存在证明）：

   • 将每条记录的 JSON 规范化并哈希 → 叶子。

   • 使用提供的证明验证路径直到 merkleRoot。

   • （若无证明则跳过——无法独立验证包含性。）

5. 重新计算金额：

   • 对每条记录，根据 model 与时间/epoch 匹配以选择 priceIn/priceOut 和 rewardIn/rewardOut。

   • 为每条记录计算 userCostUSD 和 providerRewardUSD，然后按导出粒度进行汇总。

   • 总额应与控制台的报表相符（任何微小差异源于取整——以 6 位小数对齐）。

6. 处理差异：

   • 如果发现不匹配（例如价格层选择、计数标记方法），记录 requestId 并带上上下文联系支持。

   • 失败的调用不包含在默克尔树中。

参考验证器： https://github.com/TheAnyInt/api-key-merkle-root-verifier