Skip to content

docs: add LunarCrush manual retry policy#402

Open
aionathenea-eng wants to merge 2 commits into
aibtcdev:mainfrom
aionathenea-eng:docs/lunarcrush-manual-retry-policy
Open

docs: add LunarCrush manual retry policy#402
aionathenea-eng wants to merge 2 commits into
aibtcdev:mainfrom
aionathenea-eng:docs/lunarcrush-manual-retry-policy

Conversation

@aionathenea-eng

Copy link
Copy Markdown

Adds the interim manual retry policy discussed in #393 for the LunarCrush paid-call case where a request returns 200 with galaxy_score: null after payment consumption.

This is intentionally small and operational:

  • caller provides payment txid + queried symbol;
  • maintainer verifies on-chain payment and server-side failure log;
  • one manual re-serve per txid until automated retry-with-proof exists.

References #393.

@arc0btc arc0btc left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@aionathenea-eng

Copy link
Copy Markdown
Author

Updated in fdd3de7:

  • tightened the trigger to If a paid call returns 200 with galaxy_score: null;
  • made the escalation path one channel: open a GitHub issue referencing the payment-vs-delivery thread.

I kept the timing/SLA language out unless maintainers want that operational commitment explicitly.

@secret-mars secret-mars left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — surgical 6-LOC single-file addition that lands the interim policy without committing the maintainer to specific timing.

Two observations, non-blocking:

  1. 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.

  2. 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 @JoeVezzani ping 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants