Skip to content
BranchesTags

Repository files navigation

Arbellar-SmartContract

Soroban Smart Contract Foundation for User-Funded Atomic Arbitrage on Stellar

Rust Soroban License

Table of Contents

Overview

Arbellar-SmartContract is the on-chain Soroban/Rust foundation for Arbellar, a blockchain-powered arbitrage platform built on the Stellar network. This repository contains the smart contract architecture, security models, and protocol-level financial invariants that power user-funded atomic arbitrage execution.

Current Status: Phase 1 MVP Foundation (Documentation & Architecture)

This repository is one of three independent components:

  • Arbellar-Frontend — Next.js + TypeScript + Tailwind CSS
  • Arbellar-Backend — Node.js + Express.js + TypeScript + MongoDB
  • Arbellar-SmartContract — Stellar Soroban + Rust (this repository)

The Core Problem

Manual cryptocurrency arbitrage trading faces several critical limitations:

  1. High Barriers to Entry — Requires significant technical knowledge, capital, and constant market monitoring
  2. Timing Constraints — Human traders cannot react fast enough to capitalize on fleeting arbitrage opportunities
  3. Risk Management — Manual trading exposes users to execution risk, slippage, and partial completion
  4. Custodial Risk — Traditional platforms require users to deposit funds into centralized custodial accounts
  5. Limited Accessibility — Small retail traders are effectively excluded from profitable arbitrage opportunities
  6. Infrastructure Complexity — Building secure, automated trading infrastructure requires substantial development resources

The Solution

Arbellar provides a non-custodial, user-funded atomic arbitrage platform powered by Stellar's Soroban smart contracts. The platform enables:

  • Smart Vault Infrastructure — Users maintain ownership of their funds in protocol-controlled vaults
  • Automated Opportunity Discovery — Backend continuously scans Stellar liquidity sources for profitable arbitrage
  • Atomic Execution — Transactions execute completely or not at all, protecting user principal
  • Principal Protection — Smart contract enforces that user funds cannot be lost in failed arbitrage attempts
  • Transparent Profit Distribution — On-chain accounting ensures fair and verifiable profit splits
  • Low Barrier to Entry — Users benefit from institutional-grade arbitrage infrastructure with minimal capital

How the Platform Works

User Wallet
    │
    │ 1. User deposits funds into smart vault
    ▼
Arbellar Smart Vault (Soroban)
    │
    │ 2. Backend discovers profitable arbitrage opportunity
    ▼
Backend Opportunity Discovery
    │
    │ 3. Backend requests execution authorization
    ▼
Smart Contract Execution Authorization
    │
    │ 4. Atomic Stellar transaction executes arbitrage
    ▼
Atomic Transaction Execution
    │   ├─ Buy Asset on Market A (e.g., SDEX)
    │   ├─ Sell Asset on Market B (e.g., Soroswap)
    │   └─ Validate profitability constraints
    │
    │ 5. Principal protection enforced
    ▼
Principal Returned to Vault
    │
    │ 6. Profit calculated and distributed
    ▼
Profit Distribution (80% User / 20% Platform)
    │
    │ 7. Platform fee routed to treasury
    ▼
Treasury Fee Collection

Key Flow Characteristics

  • Non-Custodial: User wallet remains the ultimate authority
  • Atomic Execution: Designed to prevent partial transaction completion
  • Principal Protection: Failed arbitrage attempts do not consume user principal
  • Transparent Accounting: All state changes recorded on-chain
  • Backend Intelligence: Market scanning and opportunity discovery remain off-chain

Important Risk Disclosure

While Stellar provides atomic transaction semantics (operations commit together or not at all), Arbellar arbitrage is not completely risk-free. Atomic execution prevents partial completion of transaction sequences, but the following risks remain:

  • Smart contract vulnerabilities
  • Market volatility and liquidity changes
  • Slippage beyond configured tolerances
  • Oracle or market data manipulation
  • Infrastructure failures
  • Strategy or parameter errors
  • User authorization mistakes

Users should understand these risks before depositing funds.

Financial Inclusion Benefits

Arbellar democratizes access to DeFi arbitrage infrastructure:

  1. Lower Capital Requirements — Users can participate with smaller amounts than traditional arbitrage trading
  2. Non-Custodial Model — Users retain ownership of their funds at all times
  3. Low Transaction Costs — Stellar's efficient blockchain keeps execution costs minimal
  4. Transparent On-Chain State — All vault balances, executions, and profit distributions are auditable
  5. Automated Infrastructure — Users benefit from institutional-grade scanning and execution without manual effort
  6. Accessible to Retail Traders — No specialized knowledge required to participate

Target Market

  • Retail Crypto Traders — Individuals seeking passive yield from DeFi arbitrage
  • Stellar Ecosystem Users — Existing Stellar wallet holders looking for yield opportunities
  • DeFi Participants — Users familiar with decentralized finance seeking new yield sources
  • Passive Yield Seekers — Investors wanting automated, non-custodial income generation
  • Blockchain Developers — Contributors building on the Arbellar protocol
  • Future Liquidity Providers (Phase 4) — Users providing capital to protocol-owned liquidity pools

Revenue Model

Phase 1 (Current MVP)

  • Performance Fee: 20% of positive arbitrage profits
  • Profit Split: 80% to user, 20% to platform treasury
  • Fee Trigger: Only charged when arbitrage execution generates positive profit
  • No Deposit/Withdrawal Fees: Users can enter and exit vaults freely

Future Revenue Streams

  • Configurable Performance Fee (Phase 2-4): 10-20% adjustable via governance
  • Relayer/Execution Surcharge (Phase 2+): Optional priority execution fees
  • Flash Loan Fee (Phase 4): 0.09% fee on flash loan borrowed amounts
  • Treasury Routing: All platform fees route to governance-controlled treasury

Revenue Model Principles

  • Performance fees only apply to positive profits
  • Failed arbitrage attempts generate no platform fees
  • Users never pay fees on their principal deposits
  • Treasury management will transition to governance control (Phase 4)

Platform Features

Phase 1 — Core MVP (Current Foundation)

Status: 🔵 Documentation & Architecture Complete

  • ✅ User-funded smart vault infrastructure
  • ✅ Non-custodial vault accounting and authorization
  • ✅ Principal protection invariants
  • ✅ Atomic arbitrage execution boundaries
  • ✅ Profit calculation and distribution logic
  • ✅ Platform fee collection (80/20 split)
  • ✅ Treasury routing architecture
  • ✅ Emergency control framework
  • ✅ Supported assets: USDC, XLM
  • ✅ Single-hop arbitrage: USDC → XLM → USDC

Phase 2 — Multi-DEX & Multi-Asset Expansion

Status: 🟡 Planned

  • 🔄 Multi-asset support: AQUA, BTC, ETH, EURC
  • 🔄 Expanded Stellar Asset Contract ecosystem integration
  • 🔄 Additional AMM integrations beyond SDEX and Soroswap
  • 🔄 User-defined risk parameters and execution limits
  • 🔄 Dynamic vault configuration
  • 🔄 Enhanced slippage controls
  • 🔄 Multi-route execution validation

Phase 3 — AI Strategy & Multi-Hop Execution

Status: 🟡 Planned

  • 🔄 Multi-hop arbitrage: USDC → XLM → AQUA → USDC
  • 🔄 Complex routing validation
  • 🔄 AI-enhanced opportunity scoring (backend)
  • 🔄 Strategy automation and parameter optimization (backend)
  • 🔄 Advanced execution constraint validation
  • 🔄 Enhanced profitability validation

Phase 4 — Native Liquidity & Governance

Status: 🟡 Planned

  • 🔄 Protocol-owned liquidity pools
  • 🔄 Flash loan infrastructure (0.09% fee)
  • 🔄 $ARB governance token
  • 🔄 Token staking mechanisms
  • 🔄 DAO governance for protocol parameters
  • 🔄 Treasury governance and voting
  • 🔄 Fee discount mechanisms for stakers
  • 🔄 Revenue sharing for token holders

Technology Stack

Blockchain & Smart Contracts

  • Blockchain: Stellar
  • Smart Contract Platform: Soroban
  • Contract Language: Rust (Edition 2021)
  • Rust Version: 1.74+
  • Soroban SDK: 22.0.0+
  • Target: wasm32-unknown-unknown

Development Tools

  • Build Tool: Cargo
  • CLI Tooling: Stellar CLI / Soroban CLI
  • Testing Framework: Soroban Test Framework
  • CI/CD: GitHub Actions
  • Code Quality: rustfmt, clippy
  • Version Control: Git / GitHub

Integration Points

  • Stellar Asset Contracts: Native Stellar token integration
  • SDEX: Stellar Decentralized Exchange (market/orderbook intelligence via backend)
  • Soroswap: Multi-source liquidity routing (via backend)
  • Backend API: Off-chain opportunity discovery and execution coordination
  • Frontend: User vault management and transaction approval

Competitive Advantage

1. Stellar's Atomic Transaction Model

  • Fast ledger finality (~5 seconds)
  • Low transaction costs
  • Built-in atomic operation semantics
  • Native asset support

2. User-Funded Architecture

  • No platform liquidity risk
  • Users maintain ownership of capital
  • Non-custodial vault model
  • Explicit authorization boundaries

3. Soroban Programmability

  • Smart contract enforcement of financial invariants
  • On-chain principal protection
  • Transparent profit distribution
  • Auditable state transitions

4. Clear Responsibility Boundaries

  • Backend: Market intelligence and opportunity discovery
  • Smart Contracts: Authorization, accounting, and protocol invariants
  • Frontend: User interaction and wallet UX

5. Future Protocol-Owned Liquidity (Phase 4)

  • Transition from user-funded to hybrid model
  • Flash loan infrastructure without external dependencies
  • Protocol revenue from flash loan fees
  • Governance-controlled treasury and parameters

Architecture

System Architecture

graph TB
    User[User Wallet]
    Frontend[Arbellar Frontend<br/>Next.js + TypeScript]
    Backend[Arbellar Backend<br/>Node.js + Express + MongoDB]
    SmartContract[Arbellar Smart Contract<br/>Soroban + Rust]
    SDEX[SDEX<br/>Stellar DEX Orderbook]
    Soroswap[Soroswap<br/>AMM Liquidity Router]
    Treasury[Protocol Treasury]
    
    User -->|Deposit/Withdraw| SmartContract
    User -->|UI Interaction| Frontend
    Frontend -->|Transaction Signing| User
    Frontend -->|Vault Status| SmartContract
    Frontend -->|API Requests| Backend
    
    Backend -->|Market Data| SDEX
    Backend -->|Routing Data| Soroswap
    Backend -->|Opportunity Discovery| Backend
    Backend -->|Execution Request| SmartContract
    
    SmartContract -->|Validate Authorization| SmartContract
    SmartContract -->|Execute Trade| SDEX
    SmartContract -->|Execute Trade| Soroswap
    SmartContract -->|Profit Distribution| User
    SmartContract -->|Platform Fees| Treasury
    
    style SmartContract fill:#f9f,stroke:#333,stroke-width:4px
    style User fill:#bbf,stroke:#333,stroke-width:2px
    style Treasury fill:#bfb,stroke:#333,stroke-width:2px
Loading

Contract Architecture (Conceptual)

The Arbellar smart contract protocol is organized into logical responsibility domains:

Arbellar Core Protocol
│
├── Vault Module
│   ├── User vault accounting
│   ├── Deposit/withdrawal rules
│   ├── Vault balance tracking
│   └── Ownership authorization
│
├── Execution Module
│   ├── Execution authorization
│   ├── Atomic operation boundaries
│   ├── Profitability validation
│   └── Principal protection
│
├── Fee Module
│   ├── Profit calculation
│   ├── Performance fee computation
│   ├── User profit distribution
│   └── Platform fee collection
│
├── Treasury Module
│   ├── Treasury routing
│   ├── Fee accumulation
│   └── Treasury authorization
│
├── Configuration Module
│   ├── Supported asset registry
│   ├── Fee configuration
│   ├── Risk parameters
│   └── Protocol settings
│
└── Emergency Module
    ├── Pause controls
    ├── Emergency withdrawal
    └── Administrative authorization

Note: The actual contract implementation may use a single core contract with internal modular responsibilities, or multiple contracts with explicit boundaries, depending on security, atomicity, and upgrade requirements. Phase 1 prioritizes a single core vault contract for security and simplicity.

Smart Contract Responsibilities

What Smart Contracts DO

✅ Vault State Management

  • User vault balance accounting
  • Ownership and authorization
  • Deposit and withdrawal rules

✅ Asset Custody Rules

  • On-chain asset accounting
  • Principal protection invariants
  • Authorized fund movement only

✅ Execution Authorization

  • Validate execution requests
  • Enforce protocol constraints
  • Authorize atomic operations

✅ Profit Accounting

  • Calculate realized profit
  • Split profit according to fee rules
  • Track user and platform balances

✅ Fee Distribution

  • Enforce performance fee rules (20% platform, 80% user)
  • Route platform fees to treasury
  • Prevent fees on non-profitable executions

✅ Protocol Invariants

  • User principal cannot be arbitrarily reduced
  • Unauthorized actors cannot withdraw user funds
  • Failed execution does not leave partial financial state
  • Treasury destinations cannot be silently replaced

✅ Emergency Controls

  • Pause/resume protocol operations
  • Emergency administrative actions
  • Preserve user withdrawal capability where possible

What Smart Contracts DO NOT DO

❌ Market Intelligence

  • SDEX orderbook analysis (Backend responsibility)
  • Soroswap routing optimization (Backend responsibility)
  • Arbitrage opportunity discovery (Backend responsibility)
  • Profitability scoring (Backend responsibility)

❌ Off-Chain Analytics

  • Historical trade data (Backend database)
  • User portfolio analytics (Backend + Frontend)
  • Performance metrics (Backend)
  • Execution monitoring (Backend)

❌ Strategy Logic

  • Arbitrage algorithm implementation (Backend)
  • Multi-hop route selection (Backend)
  • AI-enhanced scoring (Backend)
  • Risk evaluation (Backend coordination with contract constraints)

❌ User Interface

  • Wallet connection (Frontend)
  • Transaction approval UX (Frontend)
  • Portfolio visualization (Frontend)
  • Trade history presentation (Frontend)

Responsibility Boundaries

Component Authoritative For
Smart Contract On-chain balances, vault ownership, protocol state, financial invariants, authorization rules
Backend Market data, opportunity discovery, execution coordination, analytics, off-chain state
Frontend User interaction, wallet UX, transaction approval, visualization

Security Model

Threat Model

The Arbellar protocol must defend against:

  1. Unauthorized Fund Access

    • Attackers attempting to withdraw user funds without authorization
    • Malicious backend attempting to extract user principal
    • Compromised frontend attempting to steal funds

  2. Principal Theft

    • Failed arbitrage consuming user capital
    • Incorrect profit calculations reducing user principal
    • Fee manipulation exceeding configured limits

  3. Backend Compromise

    • Malicious execution requests with invalid parameters
    • Attempts to bypass protocol constraints
    • Oracle/market data manipulation

  4. Frontend Compromise

    • Phishing attacks via fake frontend
    • Transaction parameter manipulation
    • Wallet connection exploits

  5. Smart Contract Vulnerabilities

    • Integer overflow/underflow
    • Reentrancy-like patterns (where applicable to Soroban)
    • State corruption
    • Authorization bypass
    • Arithmetic errors

  6. Governance/Admin Abuse

    • Emergency controls used to extract funds
    • Treasury destination replaced maliciously
    • Fee configuration manipulated beyond limits

Security Principles

✅ Least Privilege — Each role has minimum necessary permissions

✅ Explicit Authorization — All fund movements require explicit authorization

✅ Principal Protection — User capital protected from failed arbitrage

✅ Deterministic State — State transitions are predictable and auditable

✅ Input Validation — All parameters validated before execution

✅ Atomic Operations — Critical operations execute completely or not at all

✅ Transparent Accounting — All balances and movements recorded on-chain

✅ Upgrade Safety — Upgrade mechanisms (if any) prevent unauthorized changes

✅ Emergency Fail-Safe — Emergency controls preserve user withdrawal capability

✅ No Hidden Backdoors — No mechanism for arbitrary fund confiscation

Authorization Model

Role Capabilities
User Manage own vault deposits/withdrawals, approve execution
Execution Authority Request arbitrage execution within contract-defined constraints
Protocol Administrator Manage protocol configuration, emergency controls
Treasury Authority Control protocol-owned treasury funds
Future Governance Adjust fee parameters, protocol settings, treasury control

Critical Constraint: Backend execution authority cannot unilaterally withdraw user funds. Contract enforces principal protection and profit validation.

Contract Invariants

The following invariants must be maintained at all times:

  1. Principal Invariant — User principal balance cannot decrease except via authorized withdrawal
  2. Fee Invariant — Platform fees only charged on positive realized profit
  3. Authorization Invariant — Only authorized accounts can execute vault operations
  4. Accounting Invariant — Sum of user balances + treasury balance = total contract-controlled assets
  5. Execution Invariant — Failed execution does not leave partial financial state
  6. Treasury Invariant — Protocol fees route only to authorized treasury addresses

See docs/invariants/README.md for detailed invariant specifications.

Backend Compromise Scenario

Question: What happens if the Arbellar backend is compromised?

Answer: The smart contract enforces protocol-level constraints that limit backend authority:

  • ✅ Backend cannot withdraw user principal without user authorization
  • ✅ Backend cannot bypass maximum trade size limits
  • ✅ Backend cannot execute trades with disallowed assets
  • ✅ Backend cannot manipulate profit calculations (calculated on-chain)
  • ✅ Backend cannot redirect platform fees to unauthorized addresses
  • ✅ Emergency admin can pause protocol to prevent malicious execution

Residual Risk: A compromised backend could:

  • Refuse to execute profitable arbitrage (denial of service)
  • Provide poor-quality opportunities (reduced profitability)
  • Attempt execution with manipulated parameters (blocked by contract validation)

Users maintain the ability to withdraw their funds even if the backend is unavailable.

Frontend Compromise Scenario

Question: What happens if the frontend is compromised?

Answer: The architecture relies on:

  • ✅ User wallet remains ultimate authority (transaction signing)
  • ✅ Contract validation prevents unauthorized operations
  • ✅ Users can review transaction parameters before signing
  • ✅ No private keys stored in frontend
  • ✅ Alternative frontend implementations can access protocol

Mitigation: Users should:

  • Verify transaction parameters before approval
  • Use hardware wallets for additional security
  • Check contract addresses before interaction
  • Monitor vault balances independently

Four-Phase Roadmap

Phase Name Smart Contract Responsibility Status
Phase 1 Core MVP User vaults, authorization, accounting, atomic execution boundaries, fee distribution, treasury routing, emergency controls 🔵 Current
Phase 2 Multi-DEX & Multi-Asset Expanded asset registry, multi-route validation, enhanced execution constraints, user-configurable risk parameters 🟡 Planned
Phase 3 AI Strategy & Multi-Hop Multi-hop execution validation, complex routing constraints, strategy authorization boundaries 🟡 Planned
Phase 4 Flash Loans & Governance Protocol-owned liquidity pools, flash loan primitives (0.09% fee), $ARB token, staking, DAO governance, treasury governance 🟡 Planned

Phase 1 — Core MVP (Current)

Objective: Establish the minimal on-chain protocol foundation for user-funded arbitrage

Smart Contract Scope:

  • User vault accounting and authorization
  • Deposit and withdrawal rules
  • Supported asset configuration (USDC, XLM)
  • Principal protection invariants
  • Atomic execution authorization
  • Profit calculation and distribution (80/20 split)
  • Platform fee collection and treasury routing
  • Emergency pause controls

Arbitrage Scope:

  • Single-hop arbitrage: USDC → XLM → USDC
  • SDEX and Soroswap integration (via backend coordination)

Deliverables:

  • ✅ Project structure and Rust/Soroban scaffolding
  • ✅ Comprehensive documentation
  • ✅ Contract architecture and responsibility boundaries
  • ✅ Security model and threat analysis
  • ✅ Testing framework structure
  • ✅ CI/CD pipeline configuration
  • ⏳ Core vault contract implementation (future)
  • ⏳ Contract test suite (future)
  • ⏳ Testnet deployment (future)
  • ⏳ Security audit (future)

Phase 2 — Multi-DEX & Multi-Asset Expansion (Planned)

Objective: Expand protocol to support additional assets and DEX integrations

Smart Contract Additions:

  • Multi-asset vault support (AQUA, BTC, ETH, EURC)
  • Dynamic asset registry
  • Enhanced execution validation for multi-route arbitrage
  • User-configurable risk parameters
  • Advanced slippage controls
  • Execution limit enforcement

Backend Additions:

  • Additional AMM integrations
  • Multi-source liquidity analysis
  • Enhanced opportunity scoring

Phase 3 — AI Strategy & Multi-Hop Execution (Planned)

Objective: Enable complex multi-hop arbitrage strategies

Smart Contract Additions:

  • Multi-hop execution validation (e.g., USDC → XLM → AQUA → USDC)
  • Complex routing constraint enforcement
  • Strategy authorization boundaries
  • Enhanced profitability validation

Backend Additions:

  • AI-enhanced opportunity discovery
  • Strategy automation and optimization
  • Multi-hop route planning

Phase 4 — Native Liquidity & Governance (Planned)

Objective: Transition to protocol-owned liquidity and decentralized governance

Smart Contract Additions:

  • Protocol-owned liquidity pool contracts
  • Flash loan infrastructure (0.09% fee)
  • $ARB governance token contract
  • Token staking mechanisms
  • DAO voting and proposal execution
  • Governance-controlled fee parameters (10-20% configurable)
  • Treasury governance
  • Fee discount logic for stakers
  • Revenue sharing mechanisms

Governance Capabilities:

  • Protocol parameter adjustment
  • Fee configuration (within 10-20% bounds)
  • Treasury fund allocation
  • Emergency admin replacement
  • Protocol upgrade authorization

Project Structure

Arbellar-SmartContract/
│
├── .github/
│   └── workflows/
│       ├── ci.yml              # Continuous integration workflow
│       └── build.yml           # Contract build workflow
│
├── ci/
│   ├── README.md               # CI/CD documentation
│   └── checks/
│       └── README.md           # Quality check documentation
│
├── build/
│   └── README.md               # Build process documentation
│
├── contracts/
│   ├── README.md               # Contract overview
│   │
│   ├── vault/
│   │   └── README.md           # Vault contract documentation
│   │
│   ├── execution/
│   │   └── README.md           # Execution module documentation
│   │
│   ├── fees/
│   │   └── README.md           # Fee distribution documentation
│   │
│   ├── treasury/
│   │   └── README.md           # Treasury routing documentation
│   │
│   ├── config/
│   │   └── README.md           # Protocol configuration documentation
│   │
│   └── emergency/
│       └── README.md           # Emergency controls documentation
│
├── packages/
│   ├── types/
│   │   └── README.md           # Shared types documentation
│   └── test-utils/
│       └── README.md           # Testing utilities documentation
│
├── tests/
│   ├── README.md               # Testing strategy overview
│   ├── unit/
│   │   └── README.md           # Unit test documentation
│   ├── integration/
│   │   └── README.md           # Integration test documentation
│   ├── security/
│   │   └── README.md           # Security test documentation
│   └── e2e/
│       └── README.md           # End-to-end test documentation
│
├── scripts/
│   └── README.md               # Deployment and utility scripts
│
├── deployments/
│   ├── README.md               # Deployment documentation
│   ├── testnet/
│   │   └── README.md           # Testnet deployment guide
│   └── mainnet/
│       └── README.md           # Mainnet deployment guide
│
├── docs/
│   ├── architecture/
│   │   └── README.md           # Architectural decisions
│   ├── contracts/
│   │   └── README.md           # Contract specifications
│   ├── security/
│   │   └── README.md           # Security model and threat analysis
│   ├── invariants/
│   │   └── README.md           # Contract invariants
│   ├── integration/
│   │   └── README.md           # Backend/frontend integration guide
│   ├── deployment/
│   │   └── README.md           # Deployment procedures
│   └── roadmap/
│       └── README.md           # Detailed roadmap documentation
│
├── Cargo.toml                  # Workspace configuration
├── Cargo.lock                  # Dependency lock file (generated)
├── rust-toolchain.toml         # Rust toolchain specification
├── .gitignore                  # Git ignore rules
├── README.md                   # This file
└── LICENSE                     # MIT License

Development Setup

Prerequisites

  1. Rust (1.74+)

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

  2. Stellar CLI / Soroban CLI

    cargo install --locked stellar-cli

  3. wasm32 Target

    rustup target add wasm32-unknown-unknown

  4. Code Quality Tools

    rustup component add rustfmt clippy rust-src

Installation

# Clone the repository
git clone https://github.com/arbellar/Arbellar-SmartContract.git
cd Arbellar-SmartContract

# Install dependencies
cargo build

# Run code quality checks
cargo fmt --check
cargo clippy -- -D warnings

# Run tests (when implemented)
cargo test

Building Contracts

# Build all contracts
cargo build --target wasm32-unknown-unknown --release

# Build optimized WASM (requires soroban CLI)
stellar contract build

# Optimize WASM size
stellar contract optimize --wasm target/wasm32-unknown-unknown/release/*.wasm

Running Tests

# Run all tests
cargo test

# Run specific test suite
cargo test --package vault-contract

# Run with output
cargo test -- --nocapture

# Run security tests
cargo test --package security-tests

Testing Strategy

Test Architecture

The Arbellar testing strategy follows a comprehensive multi-layer approach:

┌─────────────────────────────────────┐
│         E2E Tests                   │  Full protocol workflows
│  - Complete arbitrage cycles        │
│  - Multi-actor scenarios            │
└─────────────────────────────────────┘
              │
┌─────────────────────────────────────┐
│    Integration Tests                │  Contract interactions
│  - Multi-contract coordination      │
│  - Stellar asset interactions       │
│  - Execution flows                  │
└─────────────────────────────────────┘
              │
┌─────────────────────────────────────┐
│      Security Tests                 │  Adversarial scenarios
│  - Unauthorized access attempts     │
│  - Principal theft attacks          │
│  - Fee manipulation                 │
│  - Invariant violations             │
└─────────────────────────────────────┘
              │
┌─────────────────────────────────────┐
│       Unit Tests                    │  Individual functions
│  - Authorization logic              │
│  - Accounting calculations          │
│  - Fee computations                 │
│  - Input validation                 │
└─────────────────────────────────────┘

Test Categories

  1. Unit Tests — Individual contract function validation
  2. Integration Tests — Multi-contract and external integration
  3. Security Tests — Adversarial testing and attack scenarios
  4. E2E Tests — Complete protocol workflow validation
  5. Invariant Tests — Property-based testing for protocol invariants

See tests/README.md for detailed testing documentation.

Deployment Model

Deployment Phases

Development
    │
    ├── Local Testing (Soroban local environment)
    │
    ▼
Testnet Deployment
    │
    ├── Contract deployment
    ├── Integration testing
    ├── Frontend/backend integration
    ├── Security validation
    │
    ▼
Security Review
    │
    ├── Internal security audit
    ├── External security audit
    ├── Invariant validation
    ├── Threat model review
    │
    ▼
Testnet Public Beta
    │
    ├── Limited user testing
    ├── Performance monitoring
    ├── Bug bounty program
    │
    ▼
Mainnet Deployment
    │
    ├── Phased rollout
    ├── Emergency admin active
    ├── Continuous monitoring
    │
    ▼
Governance Transition (Phase 4)
    │
    └── Decentralized control via DAO

Deployment Principles

  • ✅ Testnet First — All contracts tested on testnet before mainnet
  • ✅ Security Audit Required — External audit before mainnet deployment
  • ✅ Phased Rollout — Gradual mainnet deployment with monitoring
  • ✅ Emergency Controls Active — Admin controls for initial mainnet period
  • ✅ Governance Transition — Long-term plan to decentralize control (Phase 4)

See deployments/README.md for deployment procedures.

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository and create a feature branch
  2. Follow Rust/Soroban best practices
  3. Write comprehensive tests for new functionality
  4. Document architectural decisions in relevant README files
  5. Run quality checks before submitting PR: 
    cargo fmt
cargo clippy
cargo test
  6. Security-sensitive changes require additional review

Code Quality Standards

  • Follow Rust 2021 edition conventions
  • Use rustfmt for consistent formatting
  • Address all clippy warnings
  • Maintain test coverage for critical paths
  • Document public APIs and complex logic
  • Follow existing architecture patterns

License

This project is licensed under the MIT License. See LICENSE for details.

Contact & Resources

Related Repositories

⚠️ Disclaimer: This software is provided "as is" without warranty. Cryptocurrency arbitrage involves significant financial risk. Users should understand the risks before depositing funds. Smart contracts should undergo comprehensive security audits before mainnet deployment.

Built with ❤️ for the Stellar ecosystem

About

Arbellar-SmartContract provides the on-chain foundation for Arbellar, enabling secure user-funded vaults, atomic arbitrage execution, profit distribution, treasury management, risk controls, and future liquidity primitives on the Stellar ecosystem through a phased, security-first architecture.

Resources

Readme
MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages