Hyper Halal Protocol

Shariah-compliant Spot Settlement on Hyperliquid L1.

This protocol implements a Murabaha financing layer that bridges off-chain liquidity (Hyperliquid Exchange) with on-chain settlement (HyperEVM). It enforces strict asset possession and atomic spot settlement to eliminate interest (Riba) and excessive uncertainty (Gharar).

Shariah Compliance Principles

The protocol solves the issue of speculative trading and interest in DeFi by enforcing a strict Spot Settlement workflow.

1. Asset Backing: Trading is restricted to assets whitelisted by the ShariahRegistry.
2. Possession Before Sale (Qabd): The Keeper (Market Maker) must acquire the asset on the Spot market and possess it in their L1 wallet before selling it to the user.
3. Spot Settlement (Fawri): Transactions are settled immediately. No leverage, no margin, no funding rates.
4. Transparent Pricing (Murabaha): The user agrees to a cost-plus price. The Keeper buys at market price and sells to the user at a fixed markup (fee).

Architecture

The system orchestrates atomic swaps between an EVM-based user and an off-chain Market Maker (Keeper). The architecture is designed for high throughput and fault tolerance, leveraging Hyperliquid's native precompiles for zero-latency asset transfers.

sequenceDiagram
    participant User
    participant Router as MurabahaSpotRouter (EVM)
    participant Keeper as Rust Keeper (Tokio)
    participant Exchange as Hyperliquid DEX (CLOB)
    participant L1 as Hyperliquid L1 (Precompiles)

    Note over User, Router: 1. Request Phase
    User->>Router: requestBuy(Asset, USDC)
    Router->>Router: Lock USDC & Emit Event

    Note over Keeper, Exchange: 2. Acquisition Phase (Off-Chain)
    Keeper->>Router: Poll Event (WebSocket)
    Keeper->>Exchange: Buy Asset (Spot Market)
    Exchange-->>Keeper: Asset Delivered to L1 Wallet

    Note over Keeper, L1: 3. Settlement Phase (On-Chain)
    Keeper->>Router: initiateSettlement()
    Keeper->>L1: sendSpot(Asset -> Router)
    
    Note over Router, L1: 4. Finalization Phase
    Keeper->>Router: finalizeSettlement()
    Router->>L1: Verify Balance (Atomic Check)
    Router->>L1: sendSpot(Asset -> User)
    Router->>Keeper: Transfer Cost + Fee (USDC)

Loading

Project Structure

• contracts/: Solidity smart contracts deployed on HyperEVM.
  • MurabahaSpotRouter: The core settlement engine.
  • ShariahRegistry: Whitelist for compliant assets.
• keeper/: Rust-based off-chain agent.
  • Listens to EVM events.
  • Executes trades on Hyperliquid DEX.
  • Orchestrates L1 token transfers via Precompiles.

Quick Start (Local Simulation)

The repository includes a complete Docker-based simulation environment using Anvil to replicate the Hyperliquid L1 environment locally.

Prerequisites

• Docker & Docker Compose
• Rust (Cargo)
• Foundry (Forge/Cast)

1. Start Local Blockchain

Navigate to the contracts directory to start the simulation environment.

cd contracts
make up

This spins up Anvil and a persistent Foundry container.

2. Deploy Contracts

Deploy the Router, Registry, and Mock L1 Precompiles to simulate Hyperliquid's native token transfers.

make deploy

3. Run the Keeper

Start the Rust agent to listen for events and orchestrate settlement.

cd ../keeper
cargo run -p keeper_bin

License

MIT