feat: implement time-based operations and scheduling

[Georgechisom]

Summary

Implemented comprehensive time-based operations and scheduling across all relevant contracts in the Remitwise platform. This feature enables automated, recurring, and time-locked operations for bills, savings, insurance, and remittances.

Changes

Bill Payments Contract

• Scheduled bill payments: Create, modify, and cancel payment schedules
• Recurring schedules: Support for interval-based recurring payments
• Keeper-triggered execution: Public execute_due_schedules() function callable by anyone
• Missed payment handling: Tracks and handles missed scheduled payments
• Schedule queries: Get schedules by owner or ID

Savings Goals Contract

• Time-locked withdrawals: Set unlock dates to prevent early withdrawals
• Scheduled deposits: Automatic recurring deposits to savings goals
• Goal completion tracking: Automatic detection when goals are met through scheduled deposits
• Keeper-triggered execution: Public execute_due_savings_schedules() function
• Missed deposit handling: Tracks missed scheduled deposits

Insurance Contract

• Scheduled premium payments: Automatic recurring premium payments
• Policy schedule management: Create, modify, and cancel premium schedules
• Keeper-triggered execution: Public execute_due_premium_schedules() function
• Missed payment tracking: Monitors and reports missed premium payments

Remittance Split Contract

• Scheduled remittances: Automatic recurring remittance distributions
• Schedule management: Full CRUD operations for remittance schedules
• Flexible intervals: Support for custom recurring intervals

Technical Implementation

Core Features

• Unix timestamp-based: Uses env.ledger().timestamp() for all time operations
• Recurring support: Interval-based scheduling with configurable frequencies
• Storage management: Efficient schedule storage per user/contract
• Event emission: Clear events for all schedule actions and executions
• Authorization: Proper auth for create/modify/cancel, public execution for keeper pattern
• Timestamp validation: Prevents past-date scheduling and validates time-locks

Keeper Pattern

All contracts implement public execution functions that can be called by anyone (keepers):

• execute_due_schedules() - Bill payments
• execute_due_savings_schedules() - Savings goals
• execute_due_premium_schedules() - Insurance premiums

These functions:

• Check current timestamp against scheduled times
• Execute all due operations
• Handle missed executions (count and advance schedule)
• Advance recurring schedules to next due date
• Emit events for executed and missed operations

Data Structures

pub struct Schedule {
    pub id: u32,
    pub owner: Address,
    pub next_due: u64,
    pub interval: u64,
    pub recurring: bool,
    pub active: bool,
    pub created_at: u64,
    pub last_executed: Option<u64>,
    pub missed_count: u32,
}

Testing

Comprehensive test coverage including:

• ✅ Schedule creation with validation
• ✅ Schedule modification and cancellation
• ✅ On-time execution
• ✅ Missed execution handling (multiple missed periods)
• ✅ Recurring schedule advancement
• ✅ Time-lock enforcement (before and after unlock)
• ✅ Edge cases (zero interval, past dates, unauthorized access)
• ✅ Goal completion through scheduled deposits
• ✅ Integration with existing contract functionality

Test Results: All 137 tests passing across all contracts

Validation

All checks pass after rebase on latest main:

• ✅ cargo fmt -- --check
• ✅ cargo clippy --all-targets --all-features -- -D warnings
• ✅ cargo check
• ✅ cargo test --workspace (137 tests passed)

Breaking Changes

None. All changes are additive:

• New functions added to existing contracts
• Existing data structures extended with optional fields
• No modifications to existing function signatures

Usage Example

// Create a recurring bill payment schedule
let schedule_id = client.create_schedule(
    &owner,
    &bill_id,
    &next_due_timestamp,
    &86400, // Daily (24 hours in seconds)
);

// Keeper calls to execute due schedules
let executed = client.execute_due_schedules();

// Set time-lock on savings goal
client.set_time_lock(&owner, &goal_id, &unlock_timestamp);

// Create recurring savings deposit
let schedule_id = client.create_savings_schedule(
    &owner,
    &goal_id,
    &500, // Amount
    &next_due,
    &2592000, // Monthly (30 days)
);

Future Enhancements

Potential improvements for future iterations:

• Off-chain keeper service for automatic execution
• Schedule pause/resume functionality
• Batch execution optimization
• Schedule expiration dates
• Notification system for upcoming/missed schedules

Closes #42