Iterative Price Discovery

01Executive Summary

JIL Sovereign's retail lane engine determines the clearing price for each batch auction using an iterative convergence algorithm that begins at the oracle price and adjusts incrementally based on net flow (total buy volume minus total sell volume). The algorithm runs for a configurable number of iterations (default 8) with a 1% step size, clamping the clearing price to an oracle band of plus or minus 5% at every step.

After the clearing price is determined, each intent is individually evaluated against its slippage tolerance and limit price. Fees are split three ways: 50% to liquidity providers, 40% to protocol operations, and 10% to the humanitarian fund. The algorithm supports early termination when the absolute net flow drops below a threshold, optimizing processing time for balanced batches.

02Problem Statement

Determining the clearing price for a batch of trade intents is fundamentally different from continuous order book matching. In a batch auction, all intents must execute at the same price (uniform clearing), which requires discovering a price that maximizes the number of fillable intents while respecting individual constraints.

2.1 Price Discovery Challenges

• Oracle Manipulation: If the clearing price is derived solely from an oracle, attackers can manipulate the oracle to extract value from the batch. If the oracle is ignored entirely, the clearing price may diverge significantly from the global market price.
• Imbalanced Batches: A batch with heavy buy pressure should clear at a higher price than a balanced batch, but the price adjustment must be bounded to prevent artificial inflation.
• Slippage Enforcement: Each intent has a maximum acceptable slippage. The clearing price must respect individual slippage constraints, meaning some intents may not fill if the discovered price exceeds their tolerance.
• Fee Complexity: Multi-party fee splitting (LPs, operations, humanitarian) adds complexity to the clearing calculation, as fees affect the effective price experienced by each counterparty.

2.2 Why Existing Approaches Fail

03Technical Architecture

The clearing algorithm operates on a shuffled list of intents (post-VRF Fisher-Yates shuffle) and discovers the clearing price through iterative adjustment. The algorithm is deterministic - given the same inputs (oracle price, intents, parameters), it always produces the same clearing price.

3.1 Algorithm Parameters

3.2 Algorithm Steps

1. Initialize: Set clearing price to the current oracle price for the trading pair.
2. Calculate net flow: Sum all buy intent amounts and subtract all sell intent amounts at the current price. Positive net flow indicates excess buying pressure; negative indicates selling pressure.
3. Early termination check: If the absolute value of net flow is less than the termination threshold, the current price is the clearing price. Exit the loop.
4. Adjust price: If net flow is positive, increase the clearing price by the step size. If negative, decrease it. This moves the price in the direction that balances supply and demand.
5. Oracle band clamp: Clamp the adjusted price to within the oracle band (oracle price +/- 5%). This prevents the algorithm from discovering a price that diverges significantly from the global market.
6. Repeat: Go to step 2 unless the maximum iteration count has been reached.
7. Intent evaluation: At the final clearing price, evaluate each intent individually. Fill intents whose slippage tolerance and limit price are satisfied. Mark unfillable intents as rejected.
8. Fee calculation: Apply the 2% DEX fee (1% buyer, 1% seller) and split according to the 50/40/10 ratio.

04Implementation

4.1 Convergence Behavior

The algorithm converges in 3 to 5 iterations for most balanced batches and uses the full 8 iterations only for heavily imbalanced batches. The oracle band clamp ensures that even in extreme cases, the clearing price stays within 5% of the external market price. The step size of 1% provides fine-grained price discovery within the band.

4.2 Intent Evaluation

After determining the clearing price, each intent is evaluated in the shuffled order. For each intent, the engine checks: (1) the clearing price is within the intent's slippage tolerance, (2) for limit orders, the clearing price satisfies the limit, and (3) sufficient pool liquidity exists to fill the intent. Intents that pass all checks are filled at the uniform clearing price. Failed intents are marked with a specific rejection reason.

4.3 Fee Distribution

05Integration with JIL Ecosystem

5.1 VRF Shuffle Integration

The iterative price discovery algorithm operates on the VRF-shuffled intent list produced by the Fisher-Yates shuffle (Claim 31). The shuffle determines the evaluation order for individual intents at the clearing price, meaning that in case of partial fills (insufficient liquidity for all intents), the shuffled order determines which intents are filled first.

5.2 Market State Adaptation

The algorithm parameters adapt to the current market state from the hysteresis state machine (Claim 30). In ELEVATED state, the oracle band may be narrowed and the step size reduced to provide more conservative price discovery. In STRESSED state, the maximum iteration count may be increased to allow more thorough convergence.

5.3 Oracle Feed

The oracle price used as the starting point and band center is sourced from the protocol's oracle infrastructure, which aggregates prices from multiple external feeds with outlier rejection. The oracle price is fetched at the start of each batch clearing and held constant throughout the iterative process.

5.4 Humanitarian Fund

The 10% humanitarian allocation is accumulated in a dedicated on-chain account and distributed according to governance decisions. The allocation is calculated and recorded for every individual fill, creating a transparent and auditable record of humanitarian contributions generated by trading activity.

06Prior Art Differentiation

07Implementation Roadmap

08Patent Claim