feat: Operator account fee-reserve & minimum-balance monitoring

[joelpeace48-cell]

Background & current state

Operator accounts that sign credits/payouts must hold enough XLM for transaction fees and minimum balance. If an operator account runs dry, credits and payouts silently fail with no early warning. There's currently no monitoring of operator account health.

Goal

Monitor operator/signing account balances and surface low-balance alerts (with an optional auto-topup hook) before failures occur.

Technical design

• A scheduled check (jobRunner) reads operator XLM via Horizon; computes headroom = balance - (base_reserve + fee_buffer).
• Export operator_xlm_balance + operator_headroom Prometheus metrics; alert below threshold (ties into NEW-044).
• Optional auto_topup hook: transfer from a treasury account when below threshold (guarded + audited).

Edge cases

• Multiple operator accounts → monitor each.
• Horizon unavailable → use cached last value + mark stale.
• Auto-topup treasury also low → escalate alert, don't loop.

Task breakdown

• Balance check job + metrics.
• Threshold config + alert wiring.
• Optional guarded auto-topup + audit log.
• Tests for threshold logic + stale handling.

Acceptance criteria

• A low-balance condition emits an alert before credits/payouts fail.
• Metrics exported per operator account.

Testing & verification

• Unit tests of threshold/headroom math; metric presence asserted.

Out of scope

• Full treasury management UI.

Dependencies / related

• Feeds NEW-010 payouts, NEW-044 alerts.

Difficulty: medium · Effort: M · stellar + observability

[Turawa2]

@Turawa2 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I can work on the issue perfectly and deliver a proper solution.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Turawa2 to this issue.

[CHKM001]

@CHKM001 has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

This is right up my alley. I have experience building backend services, monitoring, and scheduled jobs, and I can implement the balance checks, metrics, alerting, and test coverage while keeping the logic reliable and easy to maintain. I should have a PR ready within a day of being assigned.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @CHKM001 to this issue.

[Jayy4rl]

@Jayy4rl has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would like to work on this. please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Jayy4rl to this issue.

[trustosaretin]

@trustosaretin has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I would love to work on this issue.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @trustosaretin to this issue.

[drips-wave]

Congratulations, @Jayy4rl! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Jayy4rl: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

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

Next steps:

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

Good luck! Track your progress on GrantFox.