Stellinch

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.

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 network
• Stellar SDK: JavaScript library for Stellar network integration and HTLC management
• 1inch Limit Order Protocol: Integrated for advanced EVM escrow functionality with multi-stage timelocks
• OpenZeppelin: Security-audited contracts for safe ERC20 transfers and access control

Smart 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 side
• Multi-stage Timelock System: Unlike simple HTLCs, this implements a sophisticated three-phase withdrawal mechanism preventing permanent fund locks
• SHA-256 Cross-chain Compatibility: Uses the same hash function across both networks ensuring secret verification works seamlessly
• Access Token Gating: Public withdrawal phase requires access token ownership, adding an additional security layer
• CREATE2 Deterministic Addresses: Enables pre-computation of escrow addresses before deployment, crucial for atomic swap coordination

The 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.