QsnLimitOrder

The QsnLimitOrder contract implements an on-chain limit order book, allowing users to place orders that execute only when a target price is reached. Orders are filled by keepers who are incentivized with a small execution reward.

How It Works

Placing an Order

A user deposits an exact amount of tokenIn into the contract and specifies:

• tokenIn -- The token being sold.
• tokenOut -- The token being purchased.
• amountIn -- The exact amount of tokenIn deposited.
• minAmountOut -- The minimum acceptable amount of tokenOut (defines the limit price).
• deadline -- The expiration timestamp after which the order can no longer be executed.

The deposited tokens are held in the contract until the order is executed, expires, or is cancelled by the user.

Keeper Execution

Keepers are off-chain agents that monitor pending orders and execute them when market conditions satisfy the order's price constraint. When a keeper calls the executeOrder function:

1. The keeper routes the swap through QsnDEX pools to obtain at least minAmountOut of tokenOut.
2. The contract verifies that the output meets the user's minimum requirement.
3. The user receives tokenOut minus the keeper reward.
4. The keeper receives a 0.1% reward of the output amount as compensation for gas costs and monitoring.

This design requires no off-chain matching engine -- keepers compete to fill orders, and the on-chain verification ensures users always receive at least their specified minimum.

Expired Order Reclaim

If an order is not executed before its deadline, the depositor can call reclaimOrder to withdraw their full tokenIn deposit. No penalty is applied for expired orders.

Users may also cancel an active (non-expired) order at any time to reclaim their deposit.

Order Lifecycle

Place Order --> [Pending] --> Keeper Executes --> [Filled]
                   |
                   +--> Deadline Passes --> User Reclaims --> [Expired]
                   |
                   +--> User Cancels --> [Cancelled]

Key Parameters

Parameter	Value
Keeper reward	0.1% of output amount
Minimum order size	No enforced minimum
Maximum orders per user	No enforced limit
Order cancellation	Allowed at any time before execution

Integration Notes

• Keepers should monitor the OrderPlaced event to discover new orders.
• Profitability depends on gas costs, the 0.1% reward, and current market conditions.
• Orders are indexed by a unique order ID, emitted in the OrderPlaced event.