Frontend interface for the Arbellar user-funded atomic arbitrage dApp on Stellar.
Arbellar is an automated User-Funded Atomic Arbitrage platform built on Stellar that allows users to retain control of their capital while dedicated smart vaults provide capital for automated arbitrage execution. The frontend provides a professional, secure, and user-friendly interface for managing funds, monitoring arbitrage opportunities, and tracking performance.
- Fragmented Liquidity: Retail users struggle to monitor fragmented Stellar liquidity across multiple DEXs
- Technical Barriers: Arbitrage opportunities require sophisticated monitoring and quick execution
- Capital Risk: Traditional arbitrage systems often require users to give up control of their funds
- Manual Complexity: Manual arbitrage requires significant technical knowledge and constant monitoring
- Infrastructure Dependency: Many existing systems depend heavily on centralized infrastructure
Arbellar addresses these challenges through:
Users maintain complete control of their capital at all times through Stellar smart contracts while benefiting from automated arbitrage execution.
- SDEX Layer: Direct market and order book intelligence from Stellar's native DEX
- Soroswap Layer: Multi-source liquidity routing and AMM integration
- Arbellar Layer: Independent profitability analysis and execution orchestration
All arbitrage trades execute completely or not at all, ensuring principal protection and eliminating partial execution risks.
graph TD
A[User] --> B[Connect Wallet]
B --> C[Fund Smart Vault]
C --> D[Backend Scanner]
D --> E[SDEX Market Intelligence]
D --> F[Soroswap Liquidity/Routing]
E --> G[Arbellar Profitability Engine]
F --> G
G --> H[Risk & Slippage Validation]
H --> I[Atomic Stellar Execution]
I --> J[Principal Returned]
J --> K[Profit Distribution]
K --> L[User Dashboard]
- Connect Wallet: Users connect their Stellar wallet (Freighter, xBull, Albedo)
- Fund Smart Vault: Deposit capital into user-controlled smart vaults
- Automated Scanning: Backend continuously monitors market opportunities across SDEX and Soroswap
- Opportunity Analysis: Independent profitability analysis identifies viable arbitrage opportunities
- Risk Validation: Comprehensive slippage and profitability checks before execution
- Atomic Execution: Smart contracts execute trades atomically on Stellar
- Profit Distribution: 80% to user, 20% to platform (only on profitable trades)
- Lower Barriers: Accessible to retail users without sophisticated trading infrastructure
- Reduced Complexity: Automated execution eliminates need for technical arbitrage knowledge
- Non-Custodial Control: Users never give up control of their funds
- Low Costs: Stellar's efficient blockchain enables cost-effective execution
- Transparency: Complete visibility into performance, fees, and execution details
- Accessibility: Mobile-optimized interface for global accessibility
Note: Past performance does not guarantee future results. All investments carry risk of loss.
- Retail Crypto Users: Individual investors seeking passive yield opportunities
- Stellar Ecosystem Users: Active Stellar network participants
- DeFi Participants: Users familiar with decentralized finance protocols
- Passive Yield Seekers: Investors looking for automated income strategies
- Crypto Traders: Active traders seeking arbitrage opportunities
- Developers: Future API users and integrators (Phase 4)
- Institutional Users: Future enterprise clients (Phase 4)
- Performance Fee: 20% of arbitrage profits only when trades are profitable
- No Loss Sharing: Platform takes no fees when trades result in losses
- Transparent Fee Structure: All fees clearly displayed before execution
- Execution Surcharge: Small execution fee for trade processing (Phase 2)
- Premium Features: Advanced analytics and automation features (Phase 3)
- Flash Loan Fees: Revenue from flash loan protocol operations (Phase 4)
- API Access: Developer API usage fees (Phase 4)
Revenue projections are estimates and actual results may vary significantly.
| Phase | Name | Objective | Frontend Scope | Status |
|---|---|---|---|---|
| Phase 1 | Core MVP | User-funded arbitrage | Wallet, vault, dashboard, arbitrage, trades, P&L | Foundation |
| Phase 2 | Multi-DEX & Multi-Asset | Expand markets | Advanced trading, risk, analytics | Planned |
| Phase 3 | AI Strategy & Automation | Intelligent strategies | AI monitoring, automation, alerts | Planned |
| Phase 4 | Flash Loans & Governance | Advanced DeFi protocol | LP, flash loans, token, DAO | Planned |
- ✅ Wallet connection and account management
- ✅ Smart vault balance tracking and operations
- ✅ Real-time arbitrage opportunity monitoring
- ✅ Trade history and transaction tracking
- ✅ Basic P&L analytics and performance metrics
- ✅ Mobile-responsive design and accessibility
- ✅ Risk management and slippage protection
- Phase 2: Multi-asset support (AQUA, BTC, ETH, EURC), advanced analytics, CSV export
- Phase 3: AI-powered insights, automated strategies, external integrations
- Phase 4: Flash loan protocol, governance token, DAO participation
- Next.js 14+: React framework with App Router for optimal performance
- TypeScript: Type-safe development and improved developer experience
- Tailwind CSS: Utility-first styling for responsive design
- React: Modern user interface library with hooks and context
- Stellar SDK: Blockchain interaction and transaction management
- Freighter/xBull/Albedo: Multi-wallet provider support
- Soroban: Smart contract platform for vault and execution logic
- Horizon API: Real-time Stellar network data and status
- pnpm: Fast, disk space efficient package manager
- ESLint & TypeScript: Code quality and type safety
- GitHub Actions: Automated CI/CD pipeline with pnpm optimization
- Vercel/Netlify: Production deployment platform (future)
- Docker: Containerized deployment readiness (future)
Current status: Project structure and documentation foundation established. Implementation in progress.
Built with pnpm: This project uses pnpm for faster, more reliable, and space-efficient dependency management.
- Stellar's Fast Finality: 3-5 second transaction confirmation times
- Low Transaction Costs: Minimal fees enable profitable small-scale arbitrage
- Native SDEX Integration: Direct access to Stellar's built-in decentralized exchange
- Soroban Smart Contracts: Advanced contract capabilities with safety guarantees
- User-Funded Model: Users retain capital control unlike traditional flash loan arbitrage
- Atomic Execution: Complete transaction success or failure eliminates partial losses
- Independent Intelligence: Proprietary profitability analysis beyond simple spread detection
- Multi-Layer Strategy: SDEX + Soroswap + Arbellar logic provides comprehensive coverage
- Non-Custodial Security: Industry-leading security through user-controlled funds
- Retail-Friendly UX: Accessible interface designed for mainstream users
- Transparent Operations: Complete visibility into fees, performance, and execution
- Mobile Optimization: Full-featured mobile experience for global accessibility
- Phase-Based Roadmap: Sustainable development from MVP to advanced protocol
- Community-Driven: User feedback integration and community governance (Phase 4)
- Developer-Friendly: Future API access and integration capabilities
- Regulatory Awareness: Compliance-first development approach
graph TB
subgraph "Arbellar Frontend"
A[User Interface]
B[Wallet Integration]
C[API Client]
end
subgraph "External Systems"
D[Arbellar Backend]
E[Stellar Wallets]
end
subgraph "Stellar Network"
F[Stellar Blockchain]
G[SDEX]
H[Soroswap]
I[Smart Contracts]
end
A --> B
A --> C
B --> E
C --> D
E --> F
D --> G
D --> H
B --> I
I --> F
- UI Layer: User interface and user experience management
- Integration Layer: API and blockchain interaction boundaries
- Business Logic: Domain-specific frontend logic and state management
- Infrastructure: Configuration, routing, and system-level concerns
- Non-Custodial: No private key storage or access in frontend
- Transaction Transparency: Clear preview of all blockchain operations
- Input Validation: Comprehensive client-side validation with server verification
- Secure Communication: HTTPS-only with proper security headers
- Code Splitting: Route-based and component-based bundle optimization
- Caching Strategy: Intelligent data caching for optimal user experience
- Real-Time Updates: WebSocket integration for live data streaming
- Mobile Performance: Optimized for mobile networks and devices
- User Control: Private keys remain with users in their wallets
- No Key Storage: Frontend never accesses or stores private keys
- Wallet Signing: All transactions signed through user wallet providers
- Smart Contract Security: Audited contracts with emergency controls
- Clear Previews: Detailed transaction information before signing
- Slippage Protection: Maximum 0.3% slippage tolerance enforced
- Amount Validation: Comprehensive validation of transaction amounts
- Network Verification: Proper network and contract address validation
- Input Sanitization: All user inputs properly sanitized and validated
- Secure Headers: Content Security Policy and security headers
- API Security: Authenticated and rate-limited backend communication
- Error Handling: Secure error messages without sensitive data exposure
- HTTPS Only: All communication encrypted in transit
- Regular Audits: Security audits and dependency vulnerability scanning
- Access Control: Proper authentication and authorization boundaries
- Incident Response: Security incident response and recovery procedures
- No Guaranteed Returns: Arbitrage opportunities are not guaranteed and may result in losses
- Market Volatility: Cryptocurrency markets are highly volatile and unpredictable
- Spread Disappearance: Profitable spreads can disappear before execution
- Slippage Risk: Market movement during execution may impact profitability
- Smart Contract Vulnerabilities: Smart contracts may contain undiscovered vulnerabilities
- Network Failures: Stellar network or infrastructure downtime may prevent operations
- Wallet Risks: Wallet software vulnerabilities or user error may compromise funds
- Software Bugs: Frontend or backend software may contain bugs affecting operations
- Service Availability: Platform may experience downtime or service interruptions
- Regulatory Changes: Regulatory developments may impact platform operations
- Competitive Risks: Market competition may affect platform viability
- Team Risk: Dependency on development team and organizational continuity
Important: Only invest funds you can afford to lose. Cryptocurrency investments are highly speculative and carry substantial risk of total loss.
Arbellar-Frontend/
├── .github/workflows/ # CI/CD automation
├── app/ # Next.js App Router pages
│ ├── (marketing)/ # Public marketing pages
│ ├── (app)/ # Authenticated app interface
│ └── api-boundary/ # API integration documentation
├── components/ # Reusable UI components
├── features/ # Domain-oriented feature modules
├── lib/ # Utility libraries and integrations
├── hooks/ # Custom React hooks
├── types/ # TypeScript type definitions
├── constants/ # Application constants
├── config/ # Environment configuration
├── providers/ # React Context providers
├── styles/ # Global styles and Tailwind config
├── public/ # Static assets
├── docs/ # Project documentation
├── ci/ # CI/CD configuration
└── build/ # Build process documentation
Status: Foundation Phase
Core user-funded arbitrage implementation with essential features for production usage.
Key Deliverables:
- Complete wallet integration (Freighter, xBull, Albedo)
- Vault management with deposit/withdrawal workflows
- Real-time arbitrage opportunity monitoring
- Basic trade history and P&L tracking
- Mobile-responsive user interface
- Security audit and testing completion
Status: Planned
Expansion to multiple DEXs and asset pairs with enhanced user controls.
Key Features:
- Aqua DEX and Phoenix DEX integration
- Multi-asset support (AQUA, BTC, ETH, EURC)
- Advanced risk management controls
- Interactive analytics and reporting
- CSV export and custom report generation
Status: Planned
AI-powered insights and automated strategy management.
Key Features:
- Predictive arbitrage analytics
- AI-powered strategy recommendations
- Automated execution preferences
- External integrations (Telegram, Discord)
- Advanced performance optimization
Status: Future
Advanced DeFi protocol features with governance and flash loan integration.
Key Features:
- Soroban flash loan protocol
- Arbellar governance token
- DAO voting and proposal system
- Liquidity provider interfaces
- Developer API and SDK
Primary Focus: User interface and user experience
Responsibilities:
- User authentication and wallet integration
- Vault management interfaces
- Arbitrage opportunity visualization
- Trade history and analytics display
- Mobile-responsive design implementation
- Client-side state management
- Security-focused user interactions
What This Repository Does NOT Handle:
- Arbitrage algorithm implementation
- Market data aggregation and analysis
- Backend business logic
- Smart contract development
- Database management
- Server-side authentication
Primary Focus: Business logic and market intelligence
Responsibilities:
- Market data collection and analysis
- Arbitrage opportunity detection
- User account and preference management
- API endpoint implementation
- Database operations and data persistence
- Scanner orchestration and status management
- Performance analytics calculation
Primary Focus: On-chain operations and fund management
Responsibilities:
- User vault smart contract implementation
- Deposit and withdrawal contract logic
- Arbitrage execution contracts
- Fee distribution mechanisms
- Emergency controls and security features
- Principal protection guarantees
- Treasury routing and management
- Type Safety: Full TypeScript coverage with strict configuration
- Code Review: All changes require peer review and approval
- Testing Strategy: Comprehensive unit, integration, and e2e testing (future)
- Documentation: Clear documentation for all public interfaces and complex logic
- Performance: Optimization for loading speed and runtime efficiency
- Threat Modeling: Regular security assessment and threat analysis
- Dependency Management: Regular security audits and vulnerability patching
- Access Control: Principle of least privilege in all system interactions
- Data Protection: Secure handling of user data and transaction information
- Incident Response: Prepared incident response and recovery procedures
- Accessibility: WCAG 2.1 AA compliance for inclusive design
- Mobile First: Primary focus on mobile user experience
- Performance: Optimized for slow networks and low-end devices
- Clarity: Clear communication of complex financial concepts
- Trust: Transparent operations and clear risk communication
- Clean Architecture: Clear separation of concerns and dependency management
- Consistent Patterns: Established patterns for common operations
- Refactoring: Regular code improvement and technical debt management
- Monitoring: Comprehensive logging and error tracking
- Documentation: Up-to-date documentation for all systems and processes
- Node.js 18+: JavaScript runtime for development and building
- pnpm 8+: Package manager for dependency installation (recommended over npm/yarn)
- Git: Version control for code management
- Modern Browser: Chrome, Firefox, Safari, or Edge for development
# Clone the repository
git clone https://github.com/arbellar/arbellar-frontend.git
cd arbellar-frontend
# Install pnpm if not already installed
npm install -g pnpm
# Install dependencies
pnpm install
# Copy environment variables
cp .env.example .env.local
# Configure environment variables
# Edit .env.local with your configuration
# Start development server
pnpm dev# Development
pnpm dev # Start development server
pnpm build # Build production version
pnpm start # Start production server
pnpm lint # Run ESLint
pnpm type-check # Run TypeScript checksCopy .env.example to .env.local and configure:
# Backend API Configuration
NEXT_PUBLIC_BACKEND_API_URL=http://localhost:3001/api
NEXT_PUBLIC_BACKEND_WS_URL=ws://localhost:3001
# Stellar Network Configuration
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
# Application Configuration
NEXT_PUBLIC_APP_NAME=Arbellar
NEXT_PUBLIC_APP_VERSION=0.1.0
NEXT_PUBLIC_ENABLE_DEV_TOOLS=trueNote: Never commit sensitive environment variables to version control.
We welcome contributions from developers of all skill levels! Please see our Contributing Guide for detailed information on:
- Development setup and environment configuration
- Code standards and best practices
- Testing guidelines and procedures
- Submission process and pull request guidelines
- Community communication and support
- Read the Contributing Guide - Essential for all contributors
- Check Open Issues - Find contribution opportunities
- Look for "good first issue" - Perfect starting points for new contributors
- Join Discussions - Participate in project planning and feature discussions
# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/arbellar-frontend.git
# Install dependencies with pnpm
pnpm install
# Create a feature branch
git checkout -b feature/your-feature-name
# Make changes and test
pnpm lint && pnpm type-check && pnpm build
# Submit pull request with clear descriptionFor detailed instructions, security guidelines, and community standards, please refer to CONTRIBUTING.md.
This project is licensed under the MIT License - see the LICENSE file for details.
- GitHub Discussions: Technical questions and feature requests
- Discord: Real-time community chat (future)
- Documentation: Comprehensive guides in
/docsdirectory - Issues: Bug reports and feature suggestions
- Frontend Lead: [To be assigned]
- UX/UI Designer: [To be assigned]
- Security Advisor: [To be assigned]
- Community Manager: [To be assigned]
For security vulnerabilities, please email: security@arbellar.com Do not post security issues in public GitHub issues.
Current Status: Foundation Phase - Project structure and documentation established
Next Milestone: Phase 1 MVP implementation with core arbitrage functionality
Development Activity: Active development in progress
Community: Growing - contributions welcome
This README represents the current project vision and roadmap. Features and timelines are subject to change based on development progress and community feedback.