LumenLink

LumenLink is a decentralized bridge that enables instant, trustless token swaps between Ethereum (EVM) and Stellar networks using Hash Time-Locked Contracts (HTLC). Think of it as a secure tunnel between two different blockchain worlds that lets you swap tokens without needing to trust a central party. The bridge uses a clever cryptographic mechanism called HTLC (Hash Time-Locked Contract) that ensures either both sides of the swap complete successfully, or both sides get refunded. When you want to swap, the system generates a unique cryptographic hash and a secret preimage. The hash is public, but the preimage stays secret until the swap completes. Your tokens get locked in a smart contract on Ethereum with the hash, and the same hash gets used to lock equivalent tokens on Stellar. Both locks use the same cryptographic secret. When you reveal the preimage on one chain, it automatically unlocks the tokens on the other chain. The same secret works on both sides. If anything goes wrong, both chains have timelocks that automatically refund your tokens after a set period. This makes the system completely trustless - no central authority controls your funds, and the swap is atomic meaning either both sides complete or both refund. We invented a clever way to swap any token on Ethereum to any token on Stellar using USDC as a stable collateral. Instead of maintaining complex liquidity pools or pre-calculating prices, we simply swap to USDC before bridging and swap from USDC after bridging. This approach eliminates the need for extensive liquidity management and price calculations, making the system much more efficient and easier to maintain. The USDC acts as a universal bridge token that can be easily converted to any other token on either chain. For the token conversions, we use 1inch API to get optimal paths and transactions for swapping the initial token to USDC on Ethereum, and we use Stellar Horizon API to handle USDC to token conversion on Stellar. This dual approach leverages the best routing available on each chain - 1inch aggregates multiple DEXs on Ethereum for the best rates, while Horizon provides access to Stellar's built-in DEX for efficient token swaps. The system handles complex token conversions while maintaining the security of atomic swaps. For example, you can swap WETH on Ethereum for XLM on Stellar, and the bridge handles all the intermediate conversions through USDC as a bridge token.

LumenLink is built as a full-stack application with three main components: a React frontend for the user interface, a NestJS backend that coordinates the entire swap process, and smart contracts that implement HTLC on both chains. The frontend is a modern React app using Vite for fast development. It connects to both EVM and Stellar wallets using Wagmi hooks for MetaMask integration and the Freighter wallet extension for Stellar. The UI is clean and intuitive - you select tokens, enter amounts, and the system shows you exactly what you'll receive. The swap direction can be flipped with a single click, and real-time updates keep you informed of your swap status. For the smart contracts, we used Hardhat for creating the HTLC smart contract on Ethereum, leveraging OpenZeppelin's library for secure contract development. On the Stellar side, we used Soroban for creating the HTLC contract. We've created comprehensive tests and wrappers for easier integration, and developed custom packages for Stellar that include bindings and types, allowing us to use them seamlessly in both frontend and backend. The backend is built with NestJS and orchestrates everything through several key services. The Intent System manages swap state and coordinates cross-chain operations. The Resolver Service calculates optimal swap paths using 1inch and Stellar DEX APIs. The Relayer Service monitors blockchain events and automates cross-chain coordination. And HTLC Services interface with smart contracts on both chains. The resolver is particularly clever - it calculates the best swap path on each chain, applies haircuts for fees, and ensures the amounts line up perfectly across both networks. It uses 1inch for getting optimal swap quotes on EVM chains, which provides the best routing through multiple DEXs. On the Stellar side, it leverages Stellar's built-in decentralized exchange using strict-send and strict-receive pathfinding to find optimal swap routes. The smart contracts implement the same HTLC pattern but in their respective languages. The EVM contract is written in Solidity and handles ERC-20 tokens, while the Stellar contract is written in Rust using the Soroban SDK and works with Stellar's native token system. Both contracts have the same core functions: fund, withdraw, and refund. We solved several technical challenges during development. Initially, the system used hashlock to track swaps, but EVM transactions return a SwapId. We solved this by storing both and implementing dual lookup methods for redundancy. The relayer service monitors events on both chains and automatically triggers the next step when conditions are met, processing one swap at a time to avoid conflicts. A significant challenge we overcame was the Stellar version mismatch between testnet and mainnet. The Soroban SDK and contract deployment process differed between environments, but we successfully integrated the contract by carefully managing the deployment scripts and ensuring compatibility across both networks. This required extensive testing and adaptation of our deployment pipeline. We used 1inch API combined with Fusion API for creating intents and tried to match the functionality as closely as possible. The 1inch integration provides optimal swap routing through multiple DEXs, while we implemented our own intent system that mirrors the Fusion API's approach to managing swap state and coordination. This gives us the best of both worlds - reliable external routing with our own custom intent management. During development, we implemented a bypass flag for 1inch integration to test the core HTLC logic without external API dependencies. The system tracks swaps by both hashlock and SwapId for redundancy, allowing recovery from edge cases where one identifier fails. Instead of polling, the relayer listens to blockchain events and automatically triggers the next step, making the system more responsive and efficient. The cryptographic secret that unlocks HTLCs is stored encrypted in memory and only revealed when needed for withdrawals. The entire system is production-ready and has been tested on Sepolia testnet and Stellar testnet with real transactions. The atomic swap mechanism ensures users can trustlessly bridge between Ethereum and Stellar ecosystems without relying on centralized bridges.