[Advanced] nirium doctor: CLI preflight diagnostics for x402/MPP misconfiguration

[Eras256]

Difficulty: Advanced (senior · 7/10). ~14–20h. Node/TypeScript CLI, HTTP, protocol config validation.

Context

Every recent community x402 submission on this repo failed against the real protocol for the same class of mistake: wrong payment header name (X-PAYMENT is v1; Nirium's v2 flow uses PAYMENT-SIGNATURE), a facilitator URL that doesn't support Stellar, or a missing facilitatorApiKey (the OpenZeppelin Channels facilitator rejects unauthenticated servers on testnet too — a production lesson that cost real debugging time). None of this is obvious from the protocol spec alone; it only shows up once you try to run against the live facilitator.

Goal

A nirium doctor command in the existing nirium CLI that inspects a project's x402/MPP configuration and reports concrete, actionable problems before a developer burns an hour debugging a silent 402.

Scope / Deliverables

1. nirium doctor [--network testnet|pubnet] — reads env vars (or a --config file) for payTo, facilitatorUrl/facilitatorApiKey, secretKey/network, and MPP equivalents.
2. Validates: payTo is a well-formed Stellar G... address (not a secret key); the configured facilitator responds to a live health/getSupported call for the target network; a facilitator API key is present when the facilitator requires one; the network passphrase implied by network matches what the configured RPC endpoint reports (catches the txBadAuth "wrong network" class of bug).
3. Clear, colored pass/fail output per check, with a one-line fix suggestion for each failure — not just "invalid config".
4. --json output mode for CI use.
5. Tests: each check runs against a mocked facilitator/RPC (both the pass and fail path).
6. README section under packages/cli/README.md with example output.

Acceptance criteria

• Run against a deliberately broken config (missing facilitator key, malformed payTo, wrong network) and produce the correct diagnosis for each, proven by tests.
• Run against a known-good testnet config and report all green.
• nirium doctor --help documents every flag; lint/CI pass.

Pointers

• packages/sdk/src/index.ts — x402Serve()'s own validation (payTo regex, facilitatorApiKey requirement) is the canonical source of truth for what "valid" means; reuse or mirror it rather than re-deriving the rules.
• Facilitators: testnet https://channels.openzeppelin.com/x402/testnet, mainnet https://channels.openzeppelin.com/x402.
• Existing CLI: packages/cli/bin/nirium.js (commander-based, only has create today).

Out of scope

• Auto-fixing the misconfiguration — doctor diagnoses, it does not rewrite the caller's config.
• Protocols beyond x402/MPP.

References

• Dev docs: https://nirium.xyz/developers
• This repo's README: https://github.com/nirium-protocol/nirium-sdk/blob/main/README.md
• Contributing guide (how the GrantFox apply/assign flow works here): https://github.com/nirium-protocol/nirium-sdk/blob/main/CONTRIBUTING.md
• TypeScript SDK (npm): https://www.npmjs.com/package/nirium
• CLI (npm): https://www.npmjs.com/package/nirium-cli
• MCP server (npm): https://www.npmjs.com/package/nirium-mcp
• Questions: comment directly on this issue — there's no separate community chat for this repo yet.

Reward

Eligibility is subject to GrantFox review under this campaign. Rewards are decided by GrantFox based on quality and available budget and are not guaranteed.

[M0nsxx]

I'll add a doctor command to the existing CLI that reads the same env vars x402Serve()/MPP already expect (payTo, facilitatorUrl, facilitatorApiKey, secretKey, network) and checks: payTo is a valid G... address (not a secret key), the facilitator responds on the target network, an API key is present when required, and the network passphrase matches the RPC. I'll mirror the validation that already lives in packages/sdk/src/index.ts rather than inventing new rules. Tests mock both a broken config and a known-good testnet one. ETA: 4-5 days.

[grantfox-oss]

🦊 GrantFox — @M0nsxx has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #37)
2. Your PR will be reviewed by the nirium-protocol maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@M0nsxx's PR #59 was approved and merged by @Eras256.

🏆 @M0nsxx: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (83 total points). Track your full progress on GrantFox.

👏 Great work, @M0nsxx! Keep contributing to nirium-protocol.