StellarFusion💫

StellarFusion: An Intent-Based Cross-Chain Atomic Swap Platform

StellarFusion is a Platform to both Create and Fulfil Intent-Based Cross Chain Swap Orders Between ETH <> Stellar.

Let us look at the Key Features Implemented in the project.

Order Creation and Secret Generation:

Single Fill Orders: Users create complete swap orders using a single cryptographically secure random 32-byte secret. The secret is generated using ethers.utils.randomBytes(32) and immediately hashed with SHA256 to create the hash lock that secures both source and destination escrows across chains.

Partial Fill Orders with Merkle Trees: Large orders are divided into segments (typically 4 parts) where each segment receives its own unique 32-byte secret. These individual secrets are combined into a Merkle tree structure where each leaf is generated by hashing the segment index with its secret hash using abi.encodePacked(uint64(index), secretHash). The Merkle root becomes the primary hash lock used across all escrow contracts, enabling cryptographic verification of individual segments while maintaining atomic execution guarantees.

Smart Contract Infrastructure:

Ethereum Escrow Factory Contract (0x4F25B17649F0A056138E251487c27A22D793DBA7): The factory contract on Sepolia testnet deploys individual source and destination escrow instances for each transaction. It validates timelock progression, manages security deposits of 0.001 ETH per escrow, and tracks partial fill segment usage through mapping(bytes32 => mapping(uint256 => bool)) partialFillsUsed to prevent double-spending of segments.

Stellar Escrow Factory Contract (CD3TAVDMTRSPT475FP2APSC3MRQFOHVKEMJYPUGGQRP3KS4B5UBPCFH6): The factory contract on Stellar testnet directly deploys individual source and destination escrow instances for each atomic swap transaction. It implements the same factory pattern as Ethereum, providing create_src_escrow_partial and create_dst_escrow_partial functions that validate timelock progression, manage security deposits, and track partial fill segment usage to prevent double-spending.

Token Approval Mechanisms: On Ethereum, the system uses standard ERC-20 approve and transferFrom patterns where buyers approve the factory contract to spend WETH tokens. On Stellar, the LOP contract requires users to set allowances for their tokens, which are then validated and decremented during order fulfillment through the allowance and token transfer functions.

Hash Lock and Timelock System

SHA256 Hash Locks: All escrows use SHA256 hashing for cross-chain compatibility. Secrets are validated using require(sha256(secret) == hashedSecret, "Invalid secret") in Ethereum contracts and equivalent verification in Stellar contracts using the Soroban env.crypto().sha256() function.

Four-Tier Timelock Mechanism: Each escrow enforces the following timelock windows, measured in seconds from the moment of escrow creation (as set in the codebase):

• Withdrawal Start: 60 seconds (1 minute) — The private withdrawal window opens, allowing only authorized resolvers to withdraw.
• Public Withdrawal Start: 300 seconds (5 minutes) — The public withdrawal window opens, permitting anyone with the valid secret to withdraw.
• Cancellation Start: 600 seconds (10 minutes) — The private cancellation window begins, enabling the escrow creator to cancel and recover funds.
• Public Cancellation Start: 1200 seconds (20 minutes) — The public cancellation window opens, allowing anyone to trigger cancellation for emergency recovery.

Relayer Service and Dutch Auctions

Auction Coordination: The relayer service conducts real-time Dutch auctions starting at prices slightly above market rates with 5% price reductions every 10 seconds until resolvers accept terms. Single auctions manage complete orders while segmented auctions handle multiple independent price streams for partial fill segments.

Escrow Verification and Finality: After auction completion, the relayer validates that resolvers have created both source and destination escrows by checking blockchain states for transaction existence, correct token amounts, and recent activity within reasonable time windows. Only after successful verification does the relayer enable secret sharing.

Secret Exchange Coordination: The relayer facilitates secure secret exchange by receiving secrets from buyers through authenticated endpoints, storing them temporarily, and providing them to winning resolvers upon request. For partial fills, segment-specific secrets are managed independently while maintaining the overall Merkle tree structure.

Resolver Operations and Withdrawal Process

Escrow Creation: Winning resolvers create source escrows on the source chain by calling the LOP's fillOrder function with the auction's hash lock and timelock parameters, depositing 0.001 ETH security deposit plus the required token amount. They simultaneously create destination escrows on the target chain using the escrow factory's createDstEscrow with matching parameters.

Withdrawal Window Activation: After the 60-second withdrawal window opens, resolvers can withdraw from source escrows using the buyer's secret by calling withdraw(secret) or withdrawWithProof(secret, merkleProof) for partial fills. The contracts verify the SHA256 hash matches and transfer both the token amount and security deposit to the resolver.

Cross-Chain Coordination: Resolvers must withdraw from both source and destination escrows within the timelock windows. Source escrow withdrawals transfer funds to the resolver, while destination escrow withdrawals always transfer funds to the original buyer regardless of who initiates the withdrawal, ensuring atomic swap completion.

Advanced Features and Security

Partial Fill Merkle Proof Verification: For partial fill withdrawals, resolvers must provide valid Merkle proofs using MerkleProof.verify(merkleProof, hashedSecret, leaf) where the leaf is generated from the segment index and secret hash. This enables independent segment execution while maintaining cryptographic security across the entire order.

Factory Pattern Security: The factory contracts ensure all escrows are created with validated parameters, proper timelock progression, and correct token approvals. They maintain comprehensive mappings to track escrow ownership, partial fill usage, and prevent unauthorized access or double-spending attacks.

Emergency Recovery Mechanisms: If normal execution fails, escrows include cancellation functions for creators and rescue functions for recipients that activate after extended delays, ensuring funds are never permanently locked while maintaining atomic execution guarantees during normal operation.

Implementation and Tech Stack Used:

Here, we outline the major technologies used to implement each feature described in the StellarFusion cross-chain atomic swap platform.

1. Order Creation and Secret Generation:

Single Fill Orders are implemented using Ethers.js for cryptographically secure secret generation through ethers.utils.randomBytes(32) and SHA256 hashing for cross-chain compatibility. The frontend utilizes React with TypeScript for type-safe order creation interfaces, while "React Hook Form" with "Zod validation" ensures data integrity before submission.

Partial Fill Orders with Merkle Trees leverage "OpenZeppelin's MerkleProof library" in Solidity smart contracts for Ethereum-side verification, while custom Rust implementations handle Merkle tree operations on Stellar using the "Soroban SDK". The frontend manages complex partial fill state using "React Query" for efficient data synchronization and caching.

1. Smart Contract Infrastructure:

Ethereum Smart Contracts are built using "Solidity 0.8.20" with the "Foundry" development framework for testing and deployment. The contracts utilize "OpenZeppelin" libraries for security patterns like ReentrancyGuard and standardized token interfaces. Contract interactions from the frontend are handled through "Ethers.js" with "Wagmi" React hooks for wallet integration.

Stellar Smart Contracts are developed in Rust using the Soroban SDK for WebAssembly compilation. The Stellar SDK enables JavaScript/TypeScript applications to interact with these contracts, while Freighter API provides wallet connectivity for Stellar operations.

Token Approval Mechanisms utilize standard ERC-20 patterns through Ethers.js contract interfaces on Ethereum, while Stellar operations leverage the Stellar SDK for native asset management and custom token handling through Soroban contracts.

1. Hash Lock and Timelock System:

SHA256 Hash Locks are implemented consistently across platforms using native JavaScript crypto modules in Node.js applications, Ethers.js utilities in frontend applications, and Soroban's env.crypto().sha256() function in Stellar smart contracts. This ensures cross-chain compatibility without requiring additional cryptographic libraries.

Four-Tier Timelock Mechanisms are enforced through smart contract logic written in Solidity for Ethereum and Rust/Soroban for Stellar, with precise timing validation using blockchain timestamps to coordinate the 60-second, 300-second, 600-second, and 1200-second windows across both networks.

1. Relayer Service and Dutch Auctions:

Auction Coordination is powered by Express.js server framework with WebSocket (ws library) for real-time communication. The relayer maintains auction state using AWS DynamoDB for persistence and coordinates with multiple blockchain networks through Ethers.js and Stellar SDK for cross-chain validation.

Escrow Verification and Finality leverages blockchain RPC calls through Axios HTTP client to validate transaction existence and state. The system uses Alchemy for Ethereum network access and official Stellar RPC endpoints for Stellar network verification.

Secret Exchange Coordination utilizes secure Express.js REST endpoints with CORS middleware for cross-origin requests. Secrets are temporarily stored in AWS DynamoDB with automatic expiration, while real-time updates are broadcast through WebSocket connections to all connected clients.

1. Resolver Operations and Withdrawal Process:

Escrow Creation operations are coordinated through Ethers.js contract interactions for Ethereum-side escrows and Stellar SDK with Soroban contract calls for Stellar-side operations. The CLI tools built with TypeScript and Inquirer.js provide interactive interfaces for resolver operations.

Withdrawal Window Activation relies on blockchain timestamp validation implemented in Solidity smart contracts for Ethereum and Rust/Soroban contracts for Stellar. Cross-chain coordination is maintained through the relayer's Express.js API endpoints that monitor both networks simultaneously.

1. Frontend User Experience:

The complete user interface is built using Next.js with React for server-side rendering and optimal performance. Tailwind CSS provides utility-first styling, while Framer Motion enables smooth animations and transitions. Radix UI components ensure accessibility and consistent design patterns across the application.