Stellinch

Problem Statement

This project implements a trustless cross-chain atomic swap system enabling secure trading between Base (Ethereum Layer 2) and Stellar networks without requiring intermediaries or custodians. The system uses Hash Time-Locked Contracts (HTLCs) to ensure atomic properties - either both parties receive their desired assets, or both get automatic refunds.The core innovation lies in sophisticated multi-stage timelock mechanisms that provide multiple recovery opportunities. On the Base/EVM side, it integrates with 1inch Limit Order Protocol and implements a three-stage timelock system: private withdrawal (1-6 hours), public withdrawal (6-24 hours), and automatic cancellation (24+ hours). The Stellar side uses simpler HTLCs with pre-signed transactions for claiming and refunds.Users can swap ETH for XLM through a 4-step process: setup (secret generation), funding (both parties lock assets), claiming (maker reveals secret to claim XLM), and completion (taker uses revealed secret to claim ETH). The system guarantees cryptographic security through SHA-256 hashlocks and prevents fund loss through comprehensive timelock protection.The implementation handles real mainnet transactions on Base while using Stellar testnet for demonstrations, supporting bidirectional swaps and comprehensive refund mechanisms for failed trades.

Solution

The project is built using a hybrid architecture combining Solidity smart contracts on Base with TypeScript/JavaScript for Stellar integration.Core Technologies:Hardhat & Ethers.js: EVM development framework for smart contract deployment and interaction on Base networkStellar SDK: JavaScript library for Stellar network integration and HTLC management1inch Limit Order Protocol: Integrated for advanced EVM escrow functionality with multi-stage timelocksOpenZeppelin: Security-audited contracts for safe ERC20 transfers and access controlSmart Contract Architecture: The EVM side uses an inheritance-based design with BaseEscrow as the abstract foundation, implementing IBaseEscrow interface. EscrowDst extends this with concrete withdrawal and cancellation logic. The factory pattern (EscrowFactory) enables deterministic escrow address computation using CREATE2 for gas efficiency.Stellar Integration: Custom HTLC implementation using Stellar's native transaction system with pre-signed transactions for atomic operations. The system creates payment transactions with hashlock conditions that can be claimed by revealing the secret or automatically refunded after timelock expiration.Notable Technical Implementations:Cross-chain Secret Reveal: The system cleverly uses Stellar's transparency to reveal secrets on-chain, which are then extracted and used on the EVM sideMulti-stage Timelock System: Unlike simple HTLCs, this implements a sophisticated three-phase withdrawal mechanism preventing permanent fund locksSHA-256 Cross-chain Compatibility: Uses the same hash function across both networks ensuring secret verification works seamlesslyAccess Token Gating: Public withdrawal phase requires access token ownership, adding an additional security layerCREATE2 Deterministic Addresses: Enables pre-computation of escrow addresses before deployment, crucial for atomic swap coordinationThe most technically interesting aspect is the asymmetric timelock design - Stellar uses simple time-based locks while Base implements progressive unlocking phases, providing multiple recovery mechanisms while maintaining atomic properties across fundamentally different blockchain architectures.