MoveSwap

Problem Statement

MoveSwap is a comprehensive cross-chain atomic swap protocol enabling secure token exchanges between Base (Ethereum L2) and Sui networks. The protocol combines Hash Time Lock Contracts (HTLCs) with 1inch Limit Order Protocol integration for efficient, trustless cross-chain swaps. The project includes both CLI tools and a modern React frontend for seamless user experience.🎯 Core Concepts Atomic Swaps An atomic swap is a cryptographic technique that allows the exchange of cryptocurrencies from different blockchains without requiring a trusted third party or centralized exchange.Hash Time Lock Contracts (HTLCs) HTLCs are smart contracts that use cryptographic hash functions and time-based conditions to create escrow-like functionality:Hash Lock: Funds can only be released by providing the correct secret (preimage) Time Lock: Funds are automatically refunded if not claimed within a specified timeframe The Escrow Mechanism In our design, HTLC contracts act as escrow accounts:Ethereum HTLC: Holds ETH/ERC20 tokens in smart contract escrow Sui HTLC: Holds SUI/custom tokens in Move object escrow Conditional Release: Funds only released when cryptographic conditions are met Time Protection: Auto-refund prevents indefinite locking 📁 Project Structure MoveSwap/ ├── contracts/ │ ├── ethereum/ │ │ └── HTLC.sol # Ethereum HTLC contract │ └── sui/ │ ├── sources/ │ │ └── htlc.move # Sui Move HTLC contract │ ├── Move.toml # Sui package configuration │ └── build/ # Compiled Move bytecode ├── frontend/ # React frontend application │ ├── src/ │ │ ├── App.jsx # Main application component │ │ ├── components/ # UI components │ │ └── assets/ # Static assets │ ├── package.json # Frontend dependencies │ └── vite.config.js # Vite configuration ├── test/ │ ├── atomic_swap_cli.ts # Interactive CLI for atomic swaps │ └── test_cli.js # CLI test suite ├── examples/ │ └── eth_sui_swap.ts # Complete atomic swap implementation ├── scripts/ │ └── deploy.ts # Contract deployment scripts ├── config.json # Multi-network configuration ├── package.json # Main project dependencies ├── hardhat.config.js # Hardhat configuration └── README.md # This documentation 🎯 Key Features Cross-Chain Atomic Swaps: Secure token exchanges between Base and Sui 1inch Integration: Efficient DEX integration for Base chain swaps HTLC Security: Hash Time Lock Contracts ensure atomic execution Interactive CLI: Step-by-step swap execution with progress tracking Modern Frontend: React-based UI for user-friendly swap interface Multi-Network Support: Mainnet and testnet configurations Comprehensive Testing: CLI test suite and validation tools ⚙️ Environment SetupPrerequisites Node.js: v18 or higher npm/yarn: Package manager Sui CLI: For Sui blockchain interaction Git: Version control pnpm: For frontend dependencies (optional)InstallationClone the repositorygit clone https://github.com/codeakki/MoveSwap.git cd MoveSwapInstall main dependenciesnpm installInstall frontend dependencies (optional)cd frontend npm install cd ..Copy environment templatecp env.example .env 3. Environment Variables Create a .env file with the following variables:Base ConfigurationBASE_PRIVATE_KEY=your_base_private_key_here BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEYSui ConfigurationSUI_PRIVATE_KEY=your_sui_private_key_here SUI_RPC_URL=https://sui-mainnet-rpc.allthatnode.comNetwork SelectionNETWORK=mainnet # or base-sepolia for testnetOptional: 1inch IntegrationDEV_PORTAL_API_TOKEN=your_1inch_api_keyGas ConfigurationMAX_FEE_PER_GAS=0.001 MAX_PRIORITY_FEE_PER_GAS=0.0001 GAS_LIMIT=300000Timelock Configuration (in seconds)BASE_TIMELOCK_DURATION=7200 # 2 hours SUI_TIMELOCK_DURATION=3600 # 1 hour 🔗 Smart Contracts Documentation Ethereum HTLC Contract (contracts/ethereum/HTLC.sol) Contract Structure struct Lock { bytes32 htlc_id; // Unique identifier bytes32 hashlock; // SHA256 hash of secret uint256 timelock; // Expiration timestamp address sender; // Who created the HTLC address receiver; // Who can claim the funds uint256 amount; // Amount locked bytes32 secret; // Revealed secret (initially 0) bool withdrawn; // Has been claimed bool refunded; // Has been refunded uint256 created_at; // Creation timestamp address token; // Token address (0x0 for ETH) } Core Functions createHTLC() function createHTLC( bytes32 _htlc_id, // Unique swap identifier address _receiver, // Who can claim funds bytes32 _hashlock, // SHA256(secret) uint256 _timelock, // Expiration timestamp address _token // Token address (0x0 for ETH) ) external payable Purpose: Creates a new HTLC escrow account Process:Validates timelock is in future Locks ETH (if token = 0x0) or transfers ERC20 tokens to contract Creates Lock struct with provided parameters Emits HTLCCreated event claimHTLC() function claimHTLC( bytes32 _htlc_id, // HTLC identifier bytes32 _secret // Secret that hashes to hashlock ) external Purpose: Claims funds from HTLC by revealing secret Process:Verifies caller is designated receiver Checks HTLC hasn't been withdrawn/refunded Verifies timelock hasn't expired Validates SHA256(secret) == hashlock Transfers funds to receiver Stores revealed secret Emits HTLCClaimed event refundHTLC() function refundHTLC(bytes32 _htlc_id) external Purpose: Refunds locked funds after timelock expiry Process:Verifies caller is original sender Checks HTLC hasn't been withdrawn/refunded Verifies timelock has expired Returns funds to sender Emits HTLCRefunded event getHTLC() / getSecret() View functions to query HTLC state and revealed secrets.Sui HTLC Contract (contracts/sui/sources/htlc.move) Object Structure struct HTLC has key, store { id: UID, // Sui object identifier htlc_id: vector<u8>, // Unique swap identifier hashlock: vector<u8>, // SHA256 hash of secret timelock: u64, // Expiration timestamp sender: address, // Who created the HTLC receiver: address, // Who can claim funds amount: u64, // Amount locked (in MIST) secret: vector<u8>, // Revealed secret (initially empty) withdrawn: bool, // Has been claimed refunded: bool, // Has been refunded created_at: u64, // Creation timestamp coin: Option<Coin<SUI>> // Locked SUI coins } Core Functions create_htlc() public entry fun create_htlc( clock: &Clock, // System clock for timestamps htlc_id: vector<u8>, // Unique identifier receiver: address, // Who can claim funds hashlock: vector<u8>, // SHA256 hash of secret timelock: u64, // Expiration timestamp payment: Coin<SUI>, // SUI coins to lock ctx: &mut TxContext // Transaction context ) Purpose: Creates new HTLC object with locked SUI Process:Creates HTLC object with provided parameters Stores payment coin in Option<Coin> Shares object publicly for access Emits HTLCCreatedEvent claim_with_secret() public entry fun claim_with_secret( clock: &Clock, // System clock htlc: &mut HTLC, // HTLC object to claim secret: vector<u8>, // Secret to reveal ctx: &mut TxContext // Transaction context ) Purpose: Claims SUI by revealing secret Process:Verifies caller is designated receiver Checks timelock hasn't expired Validates SHA256(secret) == hashlock Extracts coin from Option and transfers to receiver Stores revealed secret Emits HTLCClaimedEvent refund_htlc() public entry fun refund_htlc( clock: &Clock, // System clock htlc: &mut HTLC, // HTLC object to refund ctx: &mut TxContext // Transaction context ) Purpose: Refunds SUI after timelock expiry Process:Verifies caller is original sender Checks timelock has expired Returns coin to sender Emits HTLCRefundedEvent

Solution

What we built is a truly trustless cross-chain atomic swap protocol that: Works across fundamentally different blockchains (EVM vs Move) Maintains atomicity - either both sides complete or neither does Handles both native tokens and ERC20s seamlessly Provides comprehensive monitoring and error handling Scales to production with proper gas management and retry logic The most satisfying part? The protocol is completely trustless - no intermediaries, no centralized components, just pure cryptographic guarantees across two very different blockchain architectures. This project taught me that cross-chain development isn't just about connecting chains - it's about understanding the fundamental differences between blockchain paradigms and building bridges that respect each chain's unique characteristics while maintaining the security guarantees that make atomic swaps possible.