OrbitSwap

Fast, seamless token swaps powered by Stellar

🌐 Live Demo · 📸 Screenshots · ⛓️ Deployed Contract

Overview

OrbitSwap is a production-ready decentralized token swap application built on the Stellar network. Users can securely connect multiple Stellar wallets, browse supported assets, inspect Stellar DEX market information, interact with deployed Soroban smart contracts, execute token swaps, monitor transaction progress, and receive live blockchain updates through a responsive modern interface.

Features

🔐 Multi-Wallet Support — Connect with Freighter, xBull, Albedo, Rabet, and LOBSTR via StellarWalletsKit
💱 Token Swap Interface — Production-quality DEX experience with real-time quotes
📊 Market Information — Live price feeds from Stellar DEX order books
⛓️ Soroban Smart Contract — Deployed contract for swap operations with read/write support
📡 Real-Time Events — Live contract event streaming and blockchain synchronization
📝 Transaction Tracking — Full lifecycle tracking: preparing → pending → confirmed
🔔 Notifications — Toast notifications for all wallet and transaction events
📱 Responsive Design — Optimized for desktop, tablet, and mobile
♿ Accessibility — Semantic HTML, keyboard navigation, ARIA labels, focus states
🧪 Comprehensive Tests — 29 passing tests covering hooks, components, and services

Technology Stack

Layer	Technologies
Frontend	React 18, TypeScript, Vite, Tailwind CSS
Blockchain	Stellar SDK, Soroban SDK
Wallets	StellarWalletsKit (Freighter, xBull, Albedo, Rabet, LOBSTR)
Smart Contract	Soroban (Rust), deployed on Stellar Testnet
State	Zustand
Routing	React Router v6
Testing	Vitest, React Testing Library
Linting	ESLint, Prettier
Build	Vite

Architecture

orbitswap/
├── contracts/
│   └── orbitswap/
│       ├── Cargo.toml              # Soroban contract manifest
│       └── src/
│           ├── lib.rs              # Smart contract implementation
│           └── test.rs             # Contract unit tests
├── public/
│   ├── favicon.svg
│   └── wallets/                    # Wallet icon SVGs
├── src/
│   ├── components/
│   │   ├── layout/                 # Navbar, Footer, Layout
│   │   ├── swap/                   # SwapCard, AssetSelector
│   │   ├── ui/                     # Button, Skeleton, StatusBadge, Toast
│   │   └── wallet/                 # WalletSelector, WalletPanel
│   ├── constants/                  # App configuration
│   ├── contracts/                  # Contract references
│   ├── hooks/                      # Custom React hooks
│   ├── pages/                      # HomePage, HistoryPage
│   ├── providers/                  # WalletProvider, ContractProvider
│   ├── services/                   # wallet.service, stellar.service, contract.service
│   ├── store/                      # Zustand state management
│   ├── styles/                     # Global CSS with Tailwind
│   ├── test/                       # Test setup and test files
│   └── types/                      # TypeScript type definitions
├── .env.example                    # Environment variables template
├── index.html
├── package.json
├── tailwind.config.js
├── tsconfig.json
└── vite.config.ts

Installation

Prerequisites

Node.js >= 18
npm >= 9
A Stellar wallet browser extension (Freighter, xBull, Albedo, or Rabet)

Setup

# Clone the repository
git clone https://github.com/your-username/orbitswap.git
cd orbitswap

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

Environment Variables

Variable	Description	Default
`VITE_STELLAR_NETWORK`	Stellar network (`TESTNET` or `PUBLIC`)	`TESTNET`
`VITE_HORIZON_URL`	Horizon API endpoint	`https://horizon-testnet.stellar.org`
`VITE_SOROBAN_RPC_URL`	Soroban RPC endpoint	`https://soroban-testnet.stellar.org`
`VITE_CONTRACT_ID`	Deployed Soroban contract ID	`CDMFGNFKQOJ3IRFN7GYL2B6242TWQX3JXLUHUZB3CLK2HNUT7VLYMNVN`
`VITE_APP_NAME`	Application name	`OrbitSwap`
`VITE_APP_URL`	Application URL	`http://localhost:3000`

Running Locally

npm run dev

Open http://localhost:3000 in your browser.

Building for Production

npm run build
npm run preview

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

🌐 Live Demo

🔗 https://orbitswap-eta.vercel.app

Deployed on Vercel.

📸 Screenshots

Wallet Options Available

Wallet selector modal showing all 5 supported Stellar wallets: Freighter, xBull, Albedo, Rabet, and LOBSTR

Wallet Setup

OrbitSwap supports 5 Stellar wallets through StellarWalletsKit:

Wallet	Installation
Freighter	freighter.app
xBull	xbull.app
Albedo	albedo.link
Rabet	rabet.io
LOBSTR	lobstr.co

Connecting a Wallet

Click the "Connect Wallet" button in the navigation bar
Select your preferred wallet from the list
Approve the connection request in your wallet extension
Your wallet address and balance will appear in the Wallet Panel

Wallet Features

Multi-wallet switching — Switch between wallets without refreshing
Auto-reconnect — Persists wallet connection across page reloads
Address display — Shows short address with copy-to-clipboard
Balance tracking — Real-time balance updates every 15 seconds
Network badge — Displays current Stellar network

Smart Contract

Contract Overview

The OrbitSwap Soroban smart contract manages:

Asset registry — Maintains a list of supported swap assets
Swap estimation — Calculates estimated output and fees
Swap execution — Validates and executes token swaps with slippage protection
Admin controls — Pause/unpause functionality for emergency stops
Events — Emits SwapExecuted events for real-time tracking

Contract Structure

contracts/orbitswap/
├── Cargo.toml
└── src/
    ├── lib.rs       # Contract + client implementation
    └── test.rs      # Contract tests (init, swap, pause)

Deployed Contract

Network: Stellar Testnet
Contract ID: CDMFGNFKQOJ3IRFN7GYL2B6242TWQX3JXLUHUZB3CLK2HNUT7VLYMNVN
Soroban RPC: https://soroban-testnet.stellar.org
Deployer: GDQY77NYQ2A4RYCQ4PKD2BFC532ECYEKPFHPS24POUHG7L4KLDB74567

Verified Contract Call

Transaction Hash (init): 8f582b3bd3a59c4ed777e7f74f3c6b01ee859129d7658bd3999cfc9928a4ef73
Stellar Expert: View on Explorer
Network: Testnet
Function Called: init(admin: orbitswap-deployer)

This is a Soroban contract invocation (init function), fully verifiable on Stellar Explorer.

Deploying the Contract

# Install Rust and Soroban CLI
cargo install --locked soroban-cli

# Build the contract
cd contracts/orbitswap
cargo build --target wasm32-unknown-unknown --release

# Deploy to testnet (requires funded Stellar account)
soroban contract deploy \
  --wasm target/wasm32-unknown-unknown/release/orbitswap.wasm \
  --source <YOUR_SECRET_KEY> \
  --network testnet

Contract Interaction

The frontend interacts with the contract via ContractService:

Read Operations:

get_assets() — Fetch supported assets
get_swap_estimate() — Get swap quote from contract
get_balance() — Check contract balance for an asset

Write Operations:

swap() — Execute a token swap with slippage protection
add_asset() — Admin: add a new supported asset
pause() / unpause() — Admin: emergency pause controls

Real-Time Sync

Contract events are streamed via polling (every 5 seconds) using the Soroban RPC getEvents endpoint. Events are stored in the Zustand store and displayed in the Notifications panel.

Transaction Lifecycle

Every transaction goes through a defined lifecycle:

Preparing → Awaiting Wallet Approval → Signing → Submitting → Pending → Confirmed
                                                                       ↘ Failed
                                                                       ↘ Rejected
                                                                       ↘ Timeout

Status badges are displayed with color-coded indicators:

🟡 Pending states — amber/yellow pulsing dot
🟢 Confirmed — green dot
🔴 Failed/Rejected — red dot
⚪ Timeout — gray dot

Swap Flow

Connect Wallet — Select and connect a Stellar wallet
Select Assets — Choose input and output tokens from the asset selector
Enter Amount — Input the swap amount (or click MAX)
Review Quote — View exchange rate, network fee, and estimated output
Confirm Swap — Review the preview modal and confirm
Track Transaction — Monitor status with in-app tracking and Explorer links

Error Handling

The application explicitly handles these error scenarios:

Error	Display	Recovery
Wallet not installed	Installation guide + link	Install wallet, retry
Wallet rejected request	User cancelled message	Dismiss, retry
Insufficient balance	Current vs required balance	Add funds, retry
Unsupported network	Network mismatch warning	Switch network
Timeout	Transaction timeout notice	Retry transaction
Contract failure	Friendly error message	Dismiss, retry

Stellar Explorer Links

All transactions include direct links to Stellar Expert for on-chain verification.

License

Acknowledgments

Built for the Rise In Stellar Builder Challenge – Level 2 (Yellow Belt).

Built with:

Stellar — Decentralized blockchain network
Soroban — Smart contract platform
StellarWalletsKit — Multi-wallet integration

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
contracts/orbitswap		contracts/orbitswap
public		public
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
README.md		README.md
eslint.config.js		eslint.config.js
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vite.config.ts		vite.config.ts

Navigation Menu

Repository files navigation

OrbitSwap

Fast, seamless token swaps powered by Stellar

Overview

Features

Technology Stack

Architecture

Installation

Prerequisites

Setup

Environment Variables

Running Locally

Building for Production

Testing

🌐 Live Demo

📸 Screenshots

Wallet Options Available

Wallet Setup

Connecting a Wallet

Wallet Features

Smart Contract

Contract Overview

Contract Structure

Deployed Contract

Verified Contract Call

Deploying the Contract

Contract Interaction

Real-Time Sync

Transaction Lifecycle

Swap Flow

Error Handling

Stellar Explorer Links

License

Acknowledgments

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

OrbitSwap

Fast, seamless token swaps powered by Stellar

Overview

Features

Technology Stack

Architecture

Installation

Prerequisites

Setup

Environment Variables

Running Locally

Building for Production

Testing

🌐 Live Demo

📸 Screenshots

Wallet Options Available

Wallet Setup

Connecting a Wallet

Wallet Features

Smart Contract

Contract Overview

Contract Structure

Deployed Contract

Verified Contract Call

Deploying the Contract

Contract Interaction

Real-Time Sync

Transaction Lifecycle

Swap Flow

Error Handling

Stellar Explorer Links

License

Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages