P4: Tip Forwarding Module — Design & Implementation Plan

[ccp-manash]

Summary

Design doc and implementation plan for P4 (Tip Forwarding in setFeeAndPledge), implemented as an optional separate module rather than modifying the core KeepWhatsRaised flow.

• Approach: Hook pattern — extract tip handling from _pledge() into _handleTip() internal virtual, child contract overrides to forward tips atomically
• Factory changes: Zero — implementationMap already supports multiple implementations via implementationId
• Existing behavior: Completely unchanged — default _handleTip() preserves current accumulate-and-claim pattern
• Security: Thorough analysis across security, gas, proxy, Permit2, accounting, factory, testing, integration, and audit perspectives. 3 HIGH findings all mitigated (CEI ordering, DoS via blocklisting, phantom claimTip state)

What's in this PR

Design document only (docs/proposals/P4-tip-forwarding-module-design.md). No code changes yet — this is for SC team review and alignment before implementation.

Key design decisions for review

1. Is immediate forwarding a hard requirement? "Option 0" (just pass real tip to existing setFeeAndPledge, zero contract changes) is fully viable if deferred claimTip() is acceptable
2. Try/catch fallback — if platformAdmin is blocklisted by a token, tip falls back to storage instead of DoS-ing the pledge. Acceptable?
3. claimTip() behavior — no-op in forwarding variant (handles fallback-stored tips). Should it revert instead?
4. Pre-existing issues found — claimRefund()/disburseFees() lack nonReentrant, tip-only pledges create phantom NFTs. Separate PR?

Design doc sections

• Problem statement & approach comparison
• Hook pattern design (KeepWhatsRaised changes + child contract)
• Security findings (0 Critical, 3 High, 3 Medium, 3 Low — all mitigated)
• Accounting invariant verification
• Gas analysis (break-even at ~29 pledges, main value is operational simplification)
• Permit2 compatibility (zero impact)
• Factory/deployment (zero changes)
• Integration impact (events, indexers, frontend)
• Test plan (~30 test cases, invariant/fuzz tests, differential testing)
• Implementation steps
• Open questions for SC team

Proposal reference

https://hackmd.io/@vaki/SypnuDM_Wg#4-P2-Tip-Forwarding-in-setFeeAndPledge

Test plan

• SC team reviews design doc and provides feedback
• Align on open questions (immediate forwarding requirement, claimTip behavior, pre-existing issues)
• Implement based on agreed design
• Full test suite (unit, integration, invariant, fuzz, differential)
• Verify all existing KWR tests pass unchanged

🤖 Generated with Claude Code

[ccp-manash]

I don't understand anything here, just trying to help out Suvadra with vibe planning 😂