fix(contract): close circuit-breaker pause coverage gaps and add completeness audit

[iyanumajekodunmi756]

Summary

Fixes #623 — Circuit-Breaker (Pause) Completeness Audit Across All Entrypoints (Reward Tier: 🏆 S).

This is a completeness-and-proof security fix, not a new feature. The contract already had pause / unpause / require_not_paused, but the guard was not uniformly applied across every value-transferring entry point — meaning an attacker could keep moving funds while the contract was "paused". This PR:

1. Closes every coverage gap — adds require_not_paused to every fund-moving path that was missing it.
2. Checks in the audit matrix — docs/pause-completeness.md maps every entry point to {mutating, value-transferring, pause-guarded}.
3. Locks the behavior in with an integration suite — tests/pause_completeness.rs pauses the contract and asserts every value-transferring entry point is blocked (≥10 assertions), every read-only view still works, and no funds move while paused.

No pause semantics were changed: the pauser/legacy-admin distinction is untouched, the guard still panics with the same "Contract is paused" message (ContractError::ContractPaused), and only coverage gaps were closed.

---

What was missing (the bug)

Value transfer is spread across many modules (escrow.rs, streams.rs, multi_sig.rs, batch_send.rs, airdrop.rs, yield_escrow.rs, and the swap/DEX + rescue paths in lib.rs). Auditing every pub fn entry point surfaced nine fund-moving code paths that could move tokens while paused:

Path	Module	Impact
rescue_tokens (legacy admin rescue)	lib.rs	Admin could sweep funds out while paused
rescue_tokens admin action (multi-sig branch)	lib.rs	Same, via execute_admin_action
resolve_dispute (arbitrator payout)	escrow.rs	Arbitrator could pay out escrow funds while paused
create_airdrop / claim_airdrop / cancel_airdrop	airdrop.rs	Airdrop funds could move while paused
create_yield_escrow / claim_yield_escrow / cancel_yield_escrow	yield_escrow.rs	Yield-escrow funds could move while paused

All nine are now guarded with the existing require_not_paused helper.

What was already correct (and is now proven)

The following were already guarded and are now locked in by tests: send_tip, create_escrow, claim_escrow, claim_escrow_partial, cancel_escrow, create_disputable_escrow, open_stream, claim_stream, top_up_stream, close_stream, reject_stream, transfer_stream, create_multisig, approve_multisig, timeout_multisig, cancel_multisig, batch_send, batch_send_multi, create_vesting, claim_vesting, revoke_vesting, swap_exact_tokens_for_tokens, swap_tokens_for_exact_tokens, initiate_emergency_withdrawal, approve_emergency_withdrawal, execute_emergency_withdrawal, cancel_emergency_withdrawal, and mint_receipt.

Deliberately NOT pause-guarded (by design)

• pause / unpause and the admin multi-sig propose_admin_action / approve_admin_action must stay callable while paused so the circuit breaker can always be lifted. The only value-transferring branch they dispatch — rescue_tokens — is individually guarded inside execute_admin_action.
• raise_dispute only flags state and moves no funds, so it deliberately remains callable while paused.
• Read-only views (get_escrow, get_stream, get_multisig, get_admin, get_claimable, get_vesting, get_emergency_withdrawal, get_contract_stats, tip/receipt getters, estimates, etc.) keep working while paused.

---

Files changed

• contracts/finchippay-contract/src/lib.rs — guard legacy rescue_tokens and the rescue_tokens admin-action branch; document the circuit-breaker invariant on require_not_paused.
• contracts/finchippay-contract/src/escrow.rs — guard resolve_dispute.
• contracts/finchippay-contract/src/airdrop.rs — guard create_airdrop / claim_airdrop / cancel_airdrop.
• contracts/finchippay-contract/src/yield_escrow.rs — guard create_yield_escrow / claim_yield_escrow / cancel_yield_escrow.
• docs/pause-completeness.md (new) — the authoritative audit matrix (all 92 entry points + internal module functions), semantics, and what the change fixed.
• contracts/finchippay-contract/tests/pause_completeness.rs (new) — the machine-checked integration suite that asserts the matrix holds.

---

Test coverage (tests/pause_completeness.rs)

Every test deploys the contract, sets up real, fully-executable on-chain state before pausing (so the only thing that can block an operation is the pause guard), pauses, then asserts the operation is blocked and no funds moved:

Test	Asserts
test_pause_blocks_tips_and_receipts	send_tip, mint_receipt blocked; balances unchanged
test_pause_blocks_escrow_and_dispute_operations	create_escrow, claim_escrow, claim_escrow_partial, cancel_escrow, create_disputable_escrow, resolve_dispute blocked; escrows stay Pending
test_pause_blocks_stream_operations	open_stream, claim_stream, top_up_stream, close_stream, reject_stream, transfer_stream blocked; stream untouched
test_pause_blocks_multisig_operations	create_multisig, approve_multisig, timeout_multisig, cancel_multisig blocked; proposal stays Pending
test_pause_blocks_batch_and_vesting_operations	batch_send, batch_send_multi, create_vesting, claim_vesting, revoke_vesting blocked
test_pause_blocks_swap_operations	both swap entry points blocked; reserves untouched
test_pause_blocks_rescue_and_emergency_withdrawal	rescue_tokens, initiate/approve/execute/cancel_emergency_withdrawal blocked
test_pause_blocks_rescue_tokens_admin_action	the rescue_tokens admin action is blocked even though propose_admin_action stays callable
test_views_work_while_paused	every read-only getter, estimate, and check_invariants still returns correct data while paused
test_governance_escape_hatches_work_while_paused	pause/unpause (pauser), admin propose/approve, set_fee_collector, set_swap_fee, transfer_admin, arbitrator management, bump_all_ttls, raise_dispute still work while paused
test_unpause_restores_value_transfer	after unpause, send_tip succeeds again

The assert_blocked_by_pause helper asserts the call errors out (the "equivalent panic" for ContractError::ContractPaused) rather than merely checking is_err() loosely — so a regression that removes the guard and lets the call through fails loudly.

---

Acceptance criteria — verified ✅

• ☑️ Checked-in matrix mapping every entry point to {mutating, pauses} → docs/pause-completeness.md, fully green.
• ☑️ While paused, no value-transferring entry point can move funds → 35+ assertions across the 11 tests (well over the required 10), each also asserting balances are unchanged.
• ☑️ Read-only getters still work while paused → test_views_work_while_paused covers get_escrow, get_stream, get_multisig, get_admin, get_admin_signers, get_claimable, get_vesting, get_emergency_withdrawal, get_contract_stats, tip/receipt getters, estimates, and more.
• ☑️ cargo test passes — 214 tests pass (203 baseline + 11 new).
• ☑️ cargo build --target wasm32v1-none --release passes.
• ☑️ cargo check --target wasm32v1-none passes (CI).
• ☑️ cargo test --test integration passes (CI).
• ☑️ No new clippy warnings from this change (the repo has pre-existing warnings that are out of scope).
• ☑️ Pause semantics unchanged — pauser/legacy-admin distinction intact; only coverage gaps closed.

---

How to verify

cd contracts/finchippay-contract
cargo test                          # 214 tests, all green
cargo test --test pause_completeness  # the new suite (11 tests)
cargo test --test integration       # existing integration suite
cargo check --target wasm32v1-none
cargo build --target wasm32v1-none --release

Notes

• This PR intentionally does not reformat pre-existing files. The repository is not cargo fmt-clean at baseline, so cargo fmt --check fails on unrelated pre-existing code; the new test file is rustfmt-clean and the diff is minimal.
• No pause semantics changed; require_not_paused remains the single source of truth for the "Contract is paused" panic.

Closes #623

[github-actions]

🤖 Greptile AI Code Review

Greptile will automatically review this PR (6 file(s) changed).

Review gates:

• ✅ CodeQL Security Scan
• ✅ Custom rules (.greptile/config.json)
• ✅ Architecture guidelines (.greptile/rules.md)

To manually trigger a re-review, comment @greptileai on this PR.
To skip review, add the skip-review label.