Insurance: convert panic!-based validation in create_policy / pay_premium to typed InsuranceError returns

[Baskarayelu]

📋 Description

Every other contract in the workspace returns a typed #[contracterror] (e.g. RemittanceSplitError, SavingsGoalError, BillPaymentsError), but insurance defines InsuranceError in insurance/src/lib.rs and then does not use it — create_policy, pay_premium, and deactivate_policy all panic! with string messages such as "monthly_premium out of range for coverage type" and "policy not found".

Why this matters: Panics abort the transaction with an opaque host error, so callers (CLI, indexer, and especially the orchestrator cross-contract flow) cannot distinguish a recoverable validation failure from a real fault. Typed errors are the contract's public ABI for failure — the insurance contract is the only one missing it.

🎯 Requirements & Context

Functional requirements

• Change create_policy, pay_premium, batch_pay_premiums, set_external_ref, deactivate_policy, get_active_policies, and get_total_monthly_premium signatures to return Result<_, InsuranceError> where they currently panic!.
• Map each existing panic to the correct existing variant: empty/too-long name → InvalidName; bad premium → InvalidPremium; bad coverage → InvalidCoverageAmount; ratio guard → UnsupportedCombination; bad external ref → InvalidExternalRef; cap hit → MaxPoliciesReached; missing policy → PolicyNotFound; inactive → PolicyInactive; non-owner → Unauthorized; uninitialized → NotInitialized.
• Replace the init panic!("already initialized") with AlreadyInitialized.
• Update insurance/src/test.rs to assert Result::Err(InsuranceError::...) instead of #[should_panic].

Context & constraints

• Soroban SDK 21.7.7, #![no_std]. InsuranceClient::try_* methods become the test surface for error assertions.
• Preserve numeric error discriminants already assigned (1..11) to keep ABI stability.
• Do not change validation thresholds — this is a representation change only.

🛠️ Suggested Execution

1. Fork & branch

git checkout -b refactor/insurance-typed-errors

2. Implement changes

• Convert internal helpers require_initialized, load_policy, validate_ext_ref to return Result.
• Add Rust doc comments documenting which error each public fn can return.
• Update next_payment_scheduling_tests.rs references if affected.

3. Test & commit

cargo test -p insurance -- --nocapture
cargo clippy -p insurance --all-targets -- -D warnings

• Edge cases: ensure no remaining panic!/unwrap()/expect() in non-test code paths.

Example commit message

refactor(insurance): return typed InsuranceError instead of panicking

Wires the existing InsuranceError variants into create_policy,
pay_premium and deactivate_policy, aligning insurance with the
workspace error-handling convention.

✅ Acceptance Criteria & Guidelines

Requirement	Target
No panic!/unwrap/expect in non-test insurance code	Required
Every variant of InsuranceError reachable & tested	Required
Error coverage of converted paths	≥ 95%
cargo test -p insurance + clippy clean	Required
ABI discriminants unchanged	Required
Timeframe	96 hours from assignment

💬 Community & Support

Questions and design discussion — join the Remitwise contributor community on Discord: https://discord.gg/CtQuPZFMA

Please comment on the issue when you pick it up so we avoid duplicate work and can unblock you quickly. 🚀

[yunus-dev-codecrafter]

Hi! I’d love to take this on.
I will refactor the insurance contract in insurance/src/lib.rs using Soroban SDK 21.7.7 to transition all public entrypoints (create_policy, pay_premium, deactivate_policy, etc.) from un-typed panic! strings to structured Result<, InsuranceError> returns. I will ensure internal helpers like require_initialized and load_policy are fully converted, mapping string failures perfectly to their corresponding InsuranceError variants while preserving the existing ABI discriminants (1..11) for protocol stability. Finally, I'll update insurance/src/test.rs to consume the try* client methods to assert explicit error variants, clean out any lingering unwrap() or expect() instances from the contract logic, and verify that the module compiles completely green under cargo test and clippy.
I can have this completed within 1 hour. Could you please assign this issue to me? Thanks!

[grantfox-oss]

🦊 GrantFox — @yunus-dev-codecrafter has been assigned to this issue!

Next steps:

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@yunus-dev-codecrafter's PR #749 was approved and merged by @Baskarayelu.

🏆 @yunus-dev-codecrafter: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (293 total points). Track your full progress on GrantFox.

👏 Great work, @yunus-dev-codecrafter! Keep contributing to Remitwise-Org.