Fractional ownership

[Chigybillionz]

closes #271

Feature: Secondary Market for Fractional Ownership Shares (Orderbook DEX)

Overview

This PR introduces a robust Secondary Market for fractional property shares, enabling a liquid decentralized exchange (DEX) environment on the Stellar network. By implementing a central limit order book (CLOB) on Soroban, we empower property share owners to trade their fractional assets instantly and securely, removing the friction of traditional real estate exits.

🚀 Key Features

• Central Limit Order Book (CLOB): High-performance on-chain order book supporting precise BUY and SELL limit orders.
• FIFO Matching Engine: A deterministic matching algorithm that executes trades based on price-time priority (First-In, First-Out).
• Multi-Property Asset Support: Implementation of a PropertyShareToken (ERC1155-compatible pattern) that allows the DEX to handle multiple distinct property identifiers within a single contract.
• Granular Market Control: Integrated FractionalTradingTrait and state flags to enable or disable trading per property, providing administrators with essential governance tools.

Technical Changes

Smart Contracts

• [NEW] contracts/fractional_trading/: Contains the core PropertyShareDEX contract logic.
• [NEW] contracts/traits/fractional_trading.rs: Defines the FractionalTradingTrait for standardized interface compliance across the ecosystem.
• [MODIFY] lib.rs: Added FractionalInfo.trading_enabled flag and enable_trading() administrative function to manage market availability.

Quality Assurance

• [NEW] tests/fractional_trading_tests.rs: Comprehensive test suite covering:
  • Order placement, cancellation, and validation.
  • Partial and full order matching scenarios.
  • Complex multi-order execution and settlement.
  • Security checks for unauthorized trading attempts.

Documentation

• [NEW] docs/fractional_trading.md: Full technical integration guide for developers.
• [MODIFY] README.md: Updated feature roadmap to include the Secondary Market capabilities.

Demo Flow

1. Property Selection: A user selects a property they own fractional shares of.
2. Limit Order Placement: The user places a SELL order for 50 shares at 120 XLM/share. The shares are safely escrowed by the contract.
3. Market Matching: A buyer places a BUY order for 50 shares at the same price.
4. Settlement: The engine matches the orders, transfers the XLM to the seller, and the shares to the buyer instantly.
5. Real-time Analytics: The trade event is emitted, updating the global price history and order book depth.

Labels

dex, liquidity, real-estate-tech, soroban-smart-contract, trading-engine

thank you!!!!!!!!!!