StellarBridge

This project enables people to swap tokens directly between Ethereum and Stellar, two totally different blockchain networks. It acts as a cross-chain bridge, letting users move assets from Ethereum to Stellar or from Stellar to Ethereum without needing a centralized exchange or risky third-party bridge.

At its core, the system uses special smart contracts and blockchain logic to make sure both sides of the swap are safe and fair. Here’s how it works in simple terms:

If you want to swap tokens from Ethereum to Stellar (or vice versa), you start a transaction that temporarily locks up your tokens on your home chain.

The system creates a matching lock on the other chain.

The swap uses secure cryptographic techniques called “hashlocks” and “timelocks” to make sure you and the person you’re swapping with must both complete your parts of the trade, or else the tokens are released back to you. This removes trust—nobody can cheat or lose money if the swap isn’t finished.

The tool works in both directions: you can start a swap from Ethereum to Stellar or from Stellar to Ethereum.

Frontend: Built with Next.js and React for live swap tracking and user interaction.

Backend Relayer: Node.js (Fastify) service that manages:

Swap initiation

Resolver registration and auction

Partial fill coordination

Communication with Ethereum and Stellar contracts

Ethereum Contracts: Solidity smart contracts that lock and release tokens on the EVM chain using hashlock and timelock logic.

Stellar Contracts: Rust/Soroban smart contracts that provide similar atomic swap functionality on Stellar (preimage and timelock enforcement).

Resolvers: Decentralized actors that participate in auctions to help fill swaps (can fill entire or partial orders).

Database & Caching: Uses PostgreSQL for persistent storage and Redis for fast access, managed via Docker.

Monitoring: Uses Grafana and Prometheus for live monitoring of system health and metrics.

Secure Swap Flow User initiates a swap on the frontend, specifying source, destination, and terms.

Backend relayer creates orders on both blockchains by interacting with the respective smart contracts.

Resolvers bid for the right to fill an order; multiple resolvers can participate for partial fills.

Swap contracts enforce atomicity with hashlock and timelock:

Assets are locked with a hash(secret) on chain A.

When the party provides the secret (preimage), assets are claimable on chain B.

If a swap isn’t completed in time, assets are refunded.

UI provides real-time tracking and swap analytics for users.

Security and Deployment JWT Auth & Rate Limiting: Protects resolver APIs.

Input Validation: Uses Zod schemas.

Deployment: Ready-to-run with Docker Compose and support for production monitoring.

Implementation Endpoints Users can initiate swaps, check status, and execute fills via a REST API.

Resolvers have endpoints to register, participate in auction, and submit bids.

Testing Unit, integration, and E2E tests are implemented for smart contracts, backend, and overall system cohesion.