System Architecture

xendune consists of 32 smart contracts organized into several subsystems. Built for EVM-compatible blockchains (Solidity ^0.8.35), all contracts interact through well-defined interfaces.

Contract Hierarchy

PlatformSettings (Central Configuration)
├── ProductFactory (Product Deployment & Index)
│   ├── ProductFactoryReader (View Functions)
│   ├── ProductFactoryKeywords (Keyword Management)
│   ├── ServiceLocationIndex (Service City Index)
│   ├── PhysicalProductTemplate (Clone Template)
│   ├── VirtualProductTemplate (Clone Template)
│   ├── ServiceProductTemplate (Clone Template)
│   └── WantToBuyTemplate (Clone Template)
├── C2CFactory (OTC Trade Deployment)
│   ├── C2CFactoryReader (View Functions)
│   ├── C2CSellOrderTemplate (Clone Template)
│   ├── C2CBuyOrderTemplate (Clone Template)
│   └── C2CTradeTemplate (Clone Template)
├── AuctionFactory (Timed Auction)
│   ├── AuctionFactoryReader (View Functions)
│   └── AuctionTemplate (Clone Template)
├── ShuifangFactory (Shuifang Currency Exchange)
│   ├── ShuifangFactoryReader (View Functions)
│   ├── ShuifangEscrowTemplate (Clone Template)
│   └── ShuifangKeywords (Keyword Management)
├── DepositFactory (Merchant Deposits)
│   └── MerchantDepositTemplate (Clone Template)
├── CommunityArbitrationFactory (Community Arbitration)
│   └── CommunityArbitrationTemplate (Clone Template)
├── KeywordWeight (Search Ranking Algorithm)
├── KeywordAuction (Keyword Bid Ranking)
├── InviteRegistry (Referral Tracking)
├── CooldownManager (C2C Anti-Fraud Timer)
├── PlatformFeeSplitter (Three-Way Fee Split)
└── ArchiveStore (Generational Storage)

Clone Pattern (EIP-1167)

All product, trade, auction, and deposit contracts are deployed as minimal proxies. Factory contracts store the template (implementation) address and deploy lightweight clones using CREATE with EIP-1167 bytecode. Each clone has its own storage but delegates logic to the template contract.

This reduces per-product deployment gas from ~3 million to ~100,000.

Data Flow

Product Purchase Flow

1. Buyer calls ProductFactory.createPhysicalProduct() (or virtual/service)
2. Factory clones template and calls initialize() on new contract
3. Factory registers product in indexes (keyword mapping, seller active list, global archive)
4. Buyer calls product contract's purchase(), locking USDT
5. Seller fulfills order (ships/delivers/provides service)
6. Buyer confirms receipt, triggering _settle() which distributes funds via ProductLib.settle()

Settlement Distribution (ProductLib)

1. Calculate platform fee: orderAmount * feeRate / 10000
2. Transfer fee to platform wallet
3. Check buyer inviter → transfer buyer referral reward
4. Check seller inviter → transfer seller referral reward
5. Transfer remaining amount to seller
6. Record transaction in KeywordWeight for ranking updates

Arbitration Flow

1. Either party calls requestArbitration(orderId)
2. Product contract notifies factory: disputeCreated(address(this))
3. Admin reviews evidence off-chain
4. Admin calls resolveArbitration(orderId, winner, compensation)
5. If buyer wins: refund from escrow + optional compensation from merchant deposit
6. If seller wins: normal settlement
7. Product contract notifies factory: disputeResolved(address(this))

Storage Architecture

Active Data

• ProductFactory.activeProducts[seller] — arrays with O(1) removal using swap-and-delete
• ProductFactory.keywordToProducts[keyword] — keyword-based product index for queries
• Each seller limited to 20 active products

Historical Data (ArchiveStore)

• Generational archival pattern: each ArchiveStore holds up to 1,000 records
• Automatically creates new generation when full
• Three archive chains: products (global), seller (per-user), buyer (per-user)
• Enables unlimited history without expensive array operations

Access Control