feat(contract): Recipient-Initiated Stream Pause/Resume with Auto-Resume Deadline

[Richardkingz2019]

Summary

Closes #558

This PR adds recipient-initiated stream pause/resume to the Finchippay Soroban smart contract, with an optional auto-resume deadline. Currently, the only recipient-controlled lifecycle actions are claim_stream and the nuclear reject_stream — there is no way to temporarily halt a stream without permanently ending the payer relationship. This PR fills that UX gap.

Changes

Stream Struct Extension (lib.rs)

• Added 5 new fields to the Stream struct:
  • recipient_paused: bool — whether the stream is paused by the recipient
  • recipient_paused_at: u32 — ledger at which the recipient paused
  • recipient_paused_duration: u32 — accumulated total paused ledgers
  • auto_resume_ledger: u32 — optional deadline for auto-resume (0 = none)
  • pause_reason: Symbol — off-chain context (e.g., "kyc_review", "travel")
• Added MAX_PAUSE_LEDGERS = 6_307_200 (~1 year at 5s/ledger) to prevent indefinite pauses
• Bumped CONTRACT_VERSION from 3 to 4

New Functions

Function	Description
pause_stream_by_recipient(stream_id, recipient, auto_resume_ledger?, reason)	Recipient pauses accrual; optionally sets auto-resume deadline
resume_stream_by_recipient(stream_id, recipient)	Recipient manually resumes; accumulates pause duration
get_stream_pause_info(stream_id)	Returns (is_paused, paused_at, duration, auto_resume, reason)

Modified Functions

• _claimable: Now accounts for recipient pause — freezes token accrual while paused by subtracting both accumulated and active pause durations from the effective elapsed ledgers
• claim_stream: Added auto-resume logic — if auto_resume_ledger has passed, the stream auto-resumes before computing claimable. Persists state even when claimable == 0 to ensure auto-resume side-effects are durable
• close_stream: Accumulates and clears recipient pause state before computing final payouts. Payer can close a paused stream
• reject_stream: Accumulates and clears recipient pause state before rejection. Recipient can reject a paused stream
• transfer_stream: Accumulates and clears pause state; new recipient inherits a clean stream
• open_stream: Initializes all new pause fields to defaults

Integration Tests (16 new tests)

Test	What it covers
test_pause_and_resume_claiming_freezes	Pause stops accrual, resume restores it
test_auto_resume_on_deadline	Auto-resume triggers on claim_stream after deadline
test_auto_resume_preserves_pause_duration	Auto-resume correctly accumulates pause duration
test_cannot_pause_already_paused_stream	Double-pause is rejected
test_cannot_resume_non_paused_stream	Resume without pause is rejected
test_pause_beyond_max_ledgers_rejected	auto_resume_ledger > MAX_PAUSE_LEDGERS is rejected
test_pause_with_past_auto_resume_rejected	Past auto_resume_ledger is rejected
test_top_up_while_paused	Payer can top up a recipient-paused stream
test_close_stream_while_paused	Payer can close a paused stream
test_reject_stream_while_paused	Recipient can reject a paused stream
test_transfer_stream_clears_pause_state	Transfer clears pause state
test_pause_with_auto_resume_at_max_boundary	Boundary value of MAX_PAUSE_LEDGERS is accepted
test_claimable_does_not_change_post_pause	get_claimable returns frozen value while paused
test_only_recipient_can_pause_or_resume	Non-recipient cannot pause/resume
test_pause_info_on_unpaused_stream_returns_zeros	Info returns default values for unpaused stream
test_multiple_pause_resume_cycles	Multiple pause/resume cycles accumulate duration correctly

CI Verification

• ✅ cargo check --target wasm32v1-none passes
• ✅ cargo test — 73/74 unit tests pass (1 pre-existing batch_send_emits_batch_sent_event failure unrelated to this change)
• ✅ All 16 new integration tests pass

Architecture

contracts/finchippay-contract/
├── src/lib.rs           (+259 lines: Stream fields, new functions, modified claimable/stream lifecycle)
└── tests/integration.rs (+527 lines: 16 comprehensive pause/resume tests)

Interaction Matrix

Operation	Paused by Recipient	Behavior
claim_stream	✅ Allowed	Auto-resumes if deadline passed; computes frozen claimable
top_up_stream	✅ Allowed	No change; payer can always add funds
close_stream	✅ Allowed	Accumulates pause duration, pays accrued, refunds remainder
reject_stream	✅ Allowed	Accumulates pause duration, pays accrued, refunds remainder
transfer_stream	✅ Allowed	Accumulates pause duration; new recipient gets clean state

Use Cases Addressed

• Compliance / KYC refresh: A recipient pauses incoming streams while KYC is under review
• Travel / offline period: Pause streams so they do not accumulate claimable tokens
• Dispute in progress: Pause while negotiating — do not reject outright
• Tax threshold management: Pause near end of tax year; resume in the new year

[vercel]

@Richardkingz2019 is attempting to deploy a commit to the Topmatrixmor2014 Team on Vercel.

A member of the Team first needs to authorize it.