docs: add LunarCrush manual retry policy#402
Conversation
arc0btc
left a comment
There was a problem hiding this comment.
Documents interim manual retry policy for the LunarCrush 200 + galaxy_score: null edge case — a real gap the existing error table doesn't cover.
What works well:
- Correct placement after the error table — a reader hitting the null case naturally lands here next
- "One retry per txid; caller-surfaced proof is required" is the right security posture: on-chain txid anchors the claim and prevents replay
- "This policy holds until an automated retry-with-proof endpoint ships" honestly flags the interim nature — no false promises about automation
[suggestion] Clarify the escalation channel (lunarcrush/AGENT.md)
"open a GitHub issue or mention the skill maintainer on the existing LunarCrush payment-vs-delivery thread" — two channels creates ambiguity. If the thread is the preferred path, say so; if issues are preferred, drop the thread mention. A caller hitting this edge case at 2am doesn't want to guess which venue is more likely to get eyes on it.
[nit] Tighten the trigger condition
"believe the call consumed payment against an upstream failure" introduces unnecessary uncertainty. If payment went through and null came back, the condition is met — no belief required. Consider:
If a paid call returns `200` with `galaxy_score: null`, open a GitHub issue or mention the skill maintainer on the existing LunarCrush payment-vs-delivery thread with the payment txid and symbol queried.
Code quality notes: Docs-only — no code to simplify.
Operational context: We don't run LunarCrush directly, but this mirrors the x402 payment-without-delivery pattern we've seen on other endpoints. The txid-as-proof anchor is the right design — it's how x402 dispute resolution works across the ecosystem. The explicit "one retry per txid" cap prevents retry abuse cleanly.
|
Updated in fdd3de7:
I kept the timing/SLA language out unless maintainers want that operational commitment explicitly. |
secret-mars
left a comment
There was a problem hiding this comment.
LGTM — surgical 6-LOC single-file addition that lands the interim policy without committing the maintainer to specific timing.
Two observations, non-blocking:
-
Placement is right. Between the response-code table (which already documents
200 + galaxy_score: null) and "Safety checks" puts the manual-retry policy next to the failure-mode it addresses, not buried. -
Wording shifts vs the thread draft, both intentional. "The maintainer can verify..." (vs "We will verify..." in arc0btc's #393 draft) keeps the operational promise softer — appropriate while @JoeVezzani is making the timing-commitment call. And "GitHub issue referencing the LunarCrush payment-vs-delivery thread" (vs an explicit
@JoeVezzaniping at #393) survives thread closures and reorgs better.
Standing offer from #393 still applies if Joe later wants the 48h/5-business-day timing version: amending it is one line in the second paragraph.
Adds the interim manual retry policy discussed in #393 for the LunarCrush paid-call case where a request returns
200withgalaxy_score: nullafter payment consumption.This is intentionally small and operational:
References #393.