## [CONTRACT-44] Implement contract_health_check Diagnostic Function

[orunganiekan]

• Points: 200
• Labels: contract, observability, read-api, devops

Background

Keeper bots and monitoring systems have no single endpoint to verify that the contract is in a healthy, operational state before submitting transactions. They must check is_contract_paused, verify the token address is set, and confirm the admin key is present — three separate RPC calls. A health degradation (e.g., instance storage TTL near expiry, contract paused, no token configured) should be detectable in a single read so automated systems can alert before failures occur. This is especially important for keeper infrastructure running against mainnet where failed transactions have real costs.

Task

Define #[contracttype] pub struct HealthReport with fields: is_healthy: bool, contract_paused: bool, token_configured: bool, admin_configured: bool, instance_ttl_ledgers: u32, active_subscription_count: u64, schema_version: u32. Add contract_health_check(env: Env) -> HealthReport as a public no-auth function. Set is_healthy = !contract_paused && token_configured && admin_configured && instance_ttl_ledgers > 17_280 (more than 1 day of TTL remaining). No storage writes.

Key Files

• contract/src/lib.rs — define HealthReport; implement contract_health_check reading from storage::get_token, storage::get_admin_optional, subscription_count::get_active_count, migration::get_schema_version, env.storage().instance().get_ttl()
• contract/src/test.rs — test: freshly initialized contract returns is_healthy = true; test: after pause_contract, is_healthy = false and contract_paused = true; test: before initialize, token_configured = false and is_healthy = false

Edge Cases

• storage::get_admin_optional already returns Option<Address> — use is_some() for admin_configured
• env.storage().instance().get_ttl() returns u32 in the soroban-sdk test environment; confirm the method signature before use
• The instance_ttl_ledgers > 17_280 threshold for is_healthy is an opinionated default — document it in a code comment as "at least 1 day of TTL remaining"
• contract_health_check must be callable even before initialize (when most keys are absent) — all field reads must use unwrap_or defaults, never expect or unwrap

Acceptance Criteria

• HealthReport is a #[contracttype] struct with all 7 fields
• is_healthy computed as the conjunction of 4 conditions including TTL threshold
• All field reads use safe defaults — no panics on uninitialized contract
• Test: initialized + unpaused $\rightarrow$ is_healthy = true
• Test: paused $\rightarrow$ is_healthy = false, contract_paused = true
• Test: pre-initialize $\rightarrow$ token_configured = false, is_healthy = false
• cargo test passes with no regressions

---

[midexol]

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

Hi, I'd like to work on this issue

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

[drips-wave]

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

🧑‍💻 @chinpiang: 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 🌊