feat(contracts): support relayer-assisted claims with secure authorization

[Olasunkanmi975]

##closes #722

Summary

This PR introduces contract-side support for relayer-assisted claim execution, allowing approved relayers to submit claim transactions on behalf of recipients while preserving secure authorization guarantees.

The implementation distinguishes relayed claims from direct claims through dedicated events and includes safeguards against replay attacks and unauthorized relayer submissions.

Changes

Relayer-Aware Claim Flow

• Added a relayer-aware claim execution path.
• Allowed relayers to submit claim transactions on behalf of recipients under explicit authorization rules.
• Preserved existing direct claim behavior and compatibility.
• Ensured recipients remain the source of authorization while relayers only facilitate transaction submission.

Authorization & Security

• Added validation to ensure only authorized relayed claims are accepted.
• Implemented replay protection for relayed claim requests.
• Rejected unauthorized relayer attempts with appropriate contract errors.
• Preserved existing authorization checks for direct claim execution.

Events

• Added dedicated events for relayed claim execution.
• Distinguished relayed claims from direct claims in emitted contract events.
• Included sufficient metadata to support indexing and off-chain monitoring.

Testing

Added and updated contract tests covering:

• Successful relayer-assisted claims
• Standard direct claims
• Replay attack prevention
• Unauthorized relayer attempts
• Authorization validation
• Event emission for relayed claims
• Backward compatibility with existing claim flow

Why

Relayer-assisted claims improve user experience by allowing recipients to receive assets without always paying transaction fees directly.

This implementation provides the required contract hooks while maintaining strong authorization guarantees and replay protection.

Testing

• Added unit tests for relayer-assisted claim execution.
• Verified replay attempts are rejected.
• Verified unauthorized relayers cannot submit claims.
• Verified relayed claims emit the correct events.
• Ran the full contract test suite.

Checklist

• Relayer-aware claim path implemented
• Secure authorization rules enforced
• Replay protection implemented and tested
• Separate events emitted for relayed claims
• Unauthorized relayer attempts rejected
• Existing direct claim flow preserved
• All contract tests passing

[drips-wave]

@Olasunkanmi975 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Olasunkanmi975]

@Cedarich kindly review

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich review boss

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich

[Olasunkanmi975]

@Cedarich pleease review and merge boss

[Olasunkanmi975]

@Cedarich Noticed while verifying this fix: 7 tests in tests/delegate_tests.rs fail
with HostError(Contract, #9) — all panicking inside create_package with
a token balance of 0, before delegate logic is even reached. Confirmed
this predates today's changes by checking out ba3481d (before this
session's work) — same failures present there. Looks like a stale/
broken token-funding fixture in this test file, unrelated to the
clippy CI job I was fixing. Flagging separately since it's pre-existing.

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich

[Olasunkanmi975]

@Cedarich please merge already broski

[Cedarich]

Please can you minimize the files changed I can see change in 450 files

[Olasunkanmi975]

@Cedarich done

[Olasunkanmi975]

@Cedarich please review

[Cedarich]

@Olasunkanmi975

[Olasunkanmi975]

@Cedarich