Feature/atomic swap

[Daverisky-max]

Closes #309

---

Implement Atomic Swap Contract (HTLC)

Resolves Issue #309

Description

This pull request introduces the Atomic Swap smart contract (atomic-swap) for the Soroban ecosystem. The contract implements a Hash-Time-Locked Contract (HTLC) pattern, enabling trustless token exchanges between two parties, including cross-chain swaps.

The contract uses an independent HTLC design (one swap record per leg) to maximize flexibility and conform to standard cross-chain patterns.

Key Features Implemented:

• Swap Creation (create_swap): Initiator escrows tokens, specifying the target claimer, the hashlock (SHA-256 hash of a secret), and the timeout ledger timestamp.
• Linked Swap Acceptance (accept_swap): A helper function to safely create the second leg of an atomic swap, ensuring timelocks are nested correctly and statuses match.
• Secret Reveal & Withdrawal (withdraw): Allows the claimer to retrieve escrowed tokens by revealing the preimage of the hashlock before the timelock expires. The secret is saved on-chain, allowing the counterparty to claim the other leg.
• Timeout Refunds (refund): Allows the original depositor to reclaim their tokens if the timelock expires without a successful withdrawal.
• Replay Protection & State Queries: Ensures swap IDs are unique and adds read-only query entrypoints (get_swap, get_status) for frontend integrations.

Implementation Details

• Located in contracts/atomic_swap/.
• Included in the main workspace Cargo.toml.
• Added robust error handling and descriptive events (created, withdrawn, refunded).

Testing

• Comprehensive unit tests have been added in contracts/atomic_swap/src/test.rs.
• Test Scenarios Covered:
  • Happy Path (full swap completion for both legs).
  • Timeout functionality and refunds.
  • Verification failures (hash mismatch / wrong secret).
• Passed cargo clippy --all-targets -- -D warnings and cargo fmt --check.

Review Checklist

• Swaps created with time-locks
• Both parties must reveal secrets
• Timeout refunds escrow
• Swap is atomic (all-or-nothing)
• History tracked via persistent storage
• All tests implemented

Please review the code in feature/atomic-swap. Let me know if any further tweaks are needed before merging!

[drips-wave]

@Daverisky-max 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