Deep health, readiness probes & dependency observability — backend EPIC

[grantfox-oss]

DESCRIPTION

HealthService.check() (apps/api/src/health/health.service.ts) only pings Supabase and generic Stellar Horizon reachability. It never checks SOROBAN_RPC_URL (already defined in apps/api/src/escrow/stellar.config.ts but unused by health), even though every VELAR bond is a Soroban contract — so a healthy Horizon can mask a broken contract RPC, and there's no visibility into the platform/escrow wallet's funding status. This epic deepens the health surface into real readiness/liveness probes with dependency-specific detail.

GOAL

/health distinguishes liveness (process is up) from readiness (all real dependencies — Supabase, Horizon, Soroban RPC, escrow wallet funding — are reachable and healthy), each dependency is checked independently, and the payload carries enough detail for on-call debugging.

REQUIREMENTS

• Split into GET /health/live (process responsive, no dependency checks, always fast) and GET /health/ready (all dependency checks, used by deploy/readiness probes) — or keep GET /health as readiness and add /health/live as the new lightweight endpoint; document whichever shape is chosen.
• Add a Soroban RPC check (SOROBAN_RPC_URL) distinct from the existing Horizon check.
• Add an escrow/platform wallet funding check (low XLM balance is a real incident risk — reuse WalletService/apps/api/src/escrow/ to read balance) and surface a degraded/warning state before it's fully down.
• Keep the existing 3-second per-dependency timeout pattern; do not let one slow dependency block the others (checks already run in parallel via Promise.all — preserve that).
• Add build/version info to the payload (e.g. git SHA or package version, deploy timestamp) for on-call debugging.

ACCEPTANCE CRITERIA

• /health/live responds fast with no external calls.
• /health/ready (or /health) reports Supabase, Horizon, Soroban RPC, and escrow wallet funding independently, with HTTP 200 when healthy and 503 when any critical dependency is down.
• A simulated low/zero escrow balance is surfaced as degraded, not silently ok.
• Response time stays under 5s in normal operation (existing constraint, preserved).
• npm run build, npm run lint, npm run test pass in apps/api with NO VELAR credentials.
• docs/BACKEND.md updated with the new health contract.

NOTES

Relevant files: apps/api/src/health/health.service.ts, apps/api/src/health/health.controller.ts, apps/api/src/escrow/stellar.config.ts (SOROBAN_RPC_URL), apps/api/src/escrow/wallet.service.ts (balance reading). This EXTENDS the existing health module (originally built for issue #5) — don't rewrite the Supabase/Horizon checks, add to them (docs/AGENTS.md §3). Endpoint(s) stay unauthenticated.

No VELAR credentials required: verifiable locally/against testnet — no VELAR database credentials or service_role key.

Difficulty: Intermediate
Priority: Medium

PR REQUIREMENTS

• Ship this as a single pull request — do not split into stacked/sequential PRs.
• Your PR description must include Closes #<this-issue-number> (this issue's GitHub number) so merging auto-closes it.

CAMPAIGN REQUIREMENTS (FWC26)

To be eligible for the reward on this issue, the contributor must:

• Follow Velar on X: https://x.com/VelarApp
• Star the repository: https://github.com/Velar-Bonds/Velar
• Follow the Velar-Bonds organization on GitHub: https://github.com/Velar-Bonds

[Naajih09]

Hi, I'd like to work on this issue. I've gone through the description and acceptance criteria and I'm confident I can deliver it. I'll make sure every acceptance criterion is met and submit a clean, tested PR. Please assign it to me.

[Peculiarr7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. I’ll prioritize this immediately and ensure a reliable solution is delivered as soon as possible. Thank you!

[SofGarro]

Hi, I'd like to work on this issue. Right now the health check only looks at Supabase and general Stellar network reachability — it doesn't check the Soroban contract RPC or the platform wallet's balance, so a real problem there could go unnoticed. I'd add those two checks, split the endpoint into a fast "is the server alive" check and a fuller "are all dependencies healthy" check, and make sure a low wallet balance shows up as a warning instead of being silently fine. I'd also add basic version info to the response to help with debugging, and update the docs.

[grantfox-oss]

🦊 GrantFox — @SofGarro 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 #80)
2. Your PR will be reviewed by the Velar-Bonds 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!

@SofGarro's PR #89 was approved and merged by @josueazc.

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

👏 Great work, @SofGarro! Keep contributing to Velar-Bonds.