Implement Clawback Functionality

[Shredder401k]

Difficulty: High
Type: Advanced Feature

Summary

Implement clawback allowing sender to reclaim withdrawn tokens with receiver or governance approval.

Current Behaviour

Withdrawn tokens cannot be reclaimed.

Expected Behaviour

Sender can request clawback. Requires receiver approval OR governance multi-sig. Clawed tokens returned to sender.

Suggested Implementation

#[contracttype]
pub struct ClawbackRequest {
    pub stream_id: u64,
    pub amount: i128,
    pub reason: String,
    pub approved_by_receiver: bool,
    pub approvals: Vec<Address>,
    pub required_approvals: u32,
}

pub fn request_clawback(
    env: Env,
    stream_id: u64,
    sender: Address,
    amount: i128,
    reason: String,
) -> Result<u64, Error>

pub fn approve_clawback(
    env: Env,
    clawback_id: u64,
    approver: Address,
) -> Result<(), Error>

pub fn execute_clawback(
    env: Env,
    clawback_id: u64,
) -> Result<(), Error>

Files or Areas Likely Affected

• contracts/Contract-V1/src/lib.rs (clawback functions)
• contracts/Contract-V1/src/types.rs (ClawbackRequest)
• contracts/Contract-V1/src/storage.rs (clawback keys)
• contracts/Contract-V1/src/errors.rs (clawback errors)
• contracts/Contract-V1/src/test.rs

Acceptance Criteria

• ClawbackRequest struct defined
• request_clawback function implemented
• approve_clawback function implemented
• execute_clawback function implemented
• request requires sender authentication
• Receiver can approve own clawback
• Governance multi-sig can approve
• Amount validated (≤ withdrawn_amount)
• Transfers tokens from receiver to sender
• Includes reason field
• Cannot execute without sufficient approvals
• At least 12 tests: request, receiver approval, governance approval, execution, insufficient approvals, amount validation, multiple clawbacks, partial clawback, rejection, expired requests, events, balance updates
• Clawback is opt-in at stream creation
• Rustdoc explains clawback purpose and risks
• Code compiles without warnings

Additional Notes

Clawback is controversial - should be opt-in. Useful for compliance and error correction but can be abused.

---

[uche102]

📋 Grainlify Application

@uche102 has applied to work on this issue as part of the Grainlify program.

Hi please i would like to work on this

---

Repo Maintainers: To accept this application, review their application or assign @uche102 to this issue.

[darcszn]

Hi, I'd like to take this on.
I've looked into the issue and have a clear idea of what's causing it.
I'll dig in, write a fix, and make sure it's covered with tests if applicable.
Can I be assigned?

[grantfox-oss]

🦊 GrantFox — @darcszn has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@darcszn's PR #1562 was approved and merged by @Folex1275.

🏆 @darcszn: You earned 40 FoxPoints for this contribution! Your current tier: Builder (1,505 total points). Track your full progress on GrantFox.

👏 Great work, @darcszn! Keep contributing to StellarStream-HQ.