[#852] Document and verify historical USD conversion in PriceChart

[realproject7]

Summary

• Historical USD conversion was already fully implemented — the gap from [Research] Price chart: feasibility of USD-based chart #776 was a misidentification of column names (usd_price_per_token / plot_usd_rate were searched, but the actual column is reserve_usd_rate)
• Added comprehensive doc comment to PriceChart explaining the USD pricing formula, three-tier data accuracy model, and chart fallback behavior
• Patch version bump 0.1.20 → 0.1.21

Fixes #852

Verification findings

The existing implementation covers all requirements from #776:

• Formula: USD price = price_per_token × reserve_usd_rate where rate = priceForNextMint(PLOT→HUNT) × HUNT/USD
• Live trades: rate captured at indexing time (rate_source: 'live')
• Historical trades: backfill script with archive RPC (backfill_exact) or fallback (backfill_approx)
• Chart UX: USD/PLOT toggle, dashed lines for approximate data, auto-fallback to PLOT if no USD data
• Recommendation: close [Research] Price chart: feasibility of USD-based chart #776 — implementation is complete, only documentation was missing

Test plan

• PriceChart still renders correctly in both USD and PLOT modes
• No type or lint regressions
• Doc comment is accurate per the codebase

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
plotlink	Ignored		Apr 12, 2026 2:56am

[realproject7]

re2 APPROVE — Verified that the USD conversion implementation is already complete: reserve_usd_rate is used in PriceChart, trade indexing, cron, and backfill script. The doc comment accurately describes the formula, three-tier accuracy model, and chart fallback behavior. Agree that #776 can be closed.

[project7-interns]

Verdict: APPROVE

Summary

I verified the documentation against the codebase: PriceChart already uses trade_history.reserve_usd_rate for USD mode, live indexing stores that rate, and the repo includes the backfill script for backfill_exact / backfill_approx tiers. The PR is focused and closes the documentation gap described in #852.

Findings

• [info] GitHub checks are still pending at review time (e2e, lint-and-typecheck, visual-regression)
  • File: PR #855
  • Suggestion: Let CI finish before merge.

Decision

Approved because the code comments and PR notes match the existing implementation and satisfy the follow-up issue’s requirement to verify and document the historical USD chart behavior clearly.