Perpetual Futures Smart Contracts

This page documents perpetual-futures instruction files in execution order.

For perpetual futures:

Long locked backing = SOL.
Short locked backing = USDC.

open_perp_position.rs

Current flow:

1. Validate perp parameters, owner, pool, custodies, oracle accounts, funding account, and token accounts.
2. Read current prices.
3. Calculate position size, collateral value, and leverage.
4. Calculate required backing liquidity.
5. For market long, check sol_custody.token_owned - sol_custody.token_locked >= required_liquidity.
6. For market short, check usdc_custody.token_owned - usdc_custody.token_locked >= required_liquidity.
7. For limit placement, skip the backing-liquidity check because no liquidity is locked yet.
8. Transfer user collateral into selected collateral custody.
9. If market order, increase locked custody token_locked.
10. Increase selected collateral custody token_owned.
11. Store position state.
12. Update pool open interest.

Liquidity check:

1. Market orders check free liquidity before locking.
2. Limit placement does not require backing liquidity because it does not lock liquidity.
3. Limit execution checks backing liquidity in execute_limit_perp.rs.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

open_limit_perp.rs

Current flow:

1. Map limit-perp parameters into open_perp_position.rs.
2. Set order_type = Limit.
3. Delegate to open_perp_position.rs.

Liquidity check:

1. It inherits the corrected limit-placement behavior from open_perp_position.rs.
2. Because a pending limit perp does not lock at placement, liquidity is checked when execute_limit_perp.rs creates the lock.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

execute_limit_perp.rs

Current flow:

1. Validate the pending perp and keeper/execution authority.
2. Check limit trigger conditions.
3. Calculate liquidation price and borrow-fee snapshot.
4. Long execution checks sol_custody.token_owned - sol_custody.token_locked >= position.locked_amount.
5. Short execution checks usdc_custody.token_owned - usdc_custody.token_locked >= position.locked_amount.
6. Long execution increases sol_custody.token_locked by position.locked_amount.
7. Short execution increases usdc_custody.token_locked by position.locked_amount.
8. Check sol_custody.token_locked <= sol_custody.token_owned.
9. Check usdc_custody.token_locked <= usdc_custody.token_owned.
10. Mark the limit position executed.

Liquidity check:

1. Current code checks free liquidity before locking.
2. Current code keeps a post-lock token_locked <= token_owned assertion.
3. Long execution requires free SOL and short execution requires free USDC.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

close_perp_position.rs

Current flow:

1. Validate the position, owner, close percentage, pool, custodies, oracle accounts, and token accounts.
2. Calculate closed size.
3. Calculate closed collateral amount.
4. Calculate PnL for the closed portion.
5. Calculate borrow interest for the closed portion.
6. Calculate trade fees for the closed portion.
7. Calculate settlement_usd = collateral + PnL - interest - trade fees, floored at zero.
8. Convert settlement into selected receive asset.
9. Calculate locked_amount_to_release.
10. If the receive asset matches the locked backing asset, require settlement_tokens <= locked_amount_to_release.
11. If the receive asset is the cross asset, require receive_custody.token_owned - receive_custody.token_locked >= settlement_tokens.
12. Transfer settlement_tokens to the user.
13. Subtract settlement_tokens from the custody that actually pays.
14. Release locked backing.
15. Reduce or close position state.
16. Update pool open interest.

Liquidity check by case:

1. Close long, receive SOL: checks settlement_tokens <= locked_amount_to_release.
2. Close long, receive USDC: checks free USDC.
3. Close short, receive USDC: checks settlement_tokens <= locked_amount_to_release.
4. Close short, receive SOL: checks free SOL.

Accounting note:

1. The file transfers settlement_tokens.
2. The file subtracts settlement_tokens from the custody that actually pays.
3. It no longer subtracts closed collateral from collateral custody as a second payout source.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

close_limit_perp.rs

Current flow:

1. This file delegates to cancel_limit_order.rs.
2. It maps close-limit-perp parameters into cancel-limit-order parameters.

Liquidity check:

1. It inherits refund logic from cancel_limit_order.rs.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

cancel_limit_order.rs

Current flow:

1. Validate pending perp, owner, pool, custodies, and token accounts.
2. Calculate proportional collateral refund.
3. Convert refund value into selected receive asset.
4. Check free liquidity in the selected receive custody.
5. Transfer refund to the user.
6. Subtract the transferred refund tokens from the selected receive custody token_owned.
7. Reduce or close the pending position.

Liquidity check:

1. Pending collateral refund is not locked backing.
2. Current code checks free liquidity before transfer.
3. The selected receive custody is the paying custody.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

update_position_size.rs

Increase flow:

1. Validate position, owner, pool, custodies, oracle accounts, and token accounts.
2. Calculate new size and collateral values.
3. Calculate required extra backing liquidity.
4. Long increase checks free SOL.
5. Short increase checks free USDC.
6. Transfer extra collateral from user to custody.
7. Increase locked custody token_locked.
8. Increase collateral custody token_owned.
9. Increase position size, collateral, and locked amount.

Increase liquidity check:

1. This path correctly checks free liquidity before increasing the lock.

Decrease flow:

1. Validate requested size decrease.
2. Calculate proportional collateral to return.
3. Calculate locked_amount_to_release.
4. Calculate PnL for the decreased portion.
5. Calculate settlement value.
6. Convert settlement into selected receive asset.
7. If the receive asset matches the locked backing asset, require the payout is bounded by locked_amount_to_release.
8. If the receive asset is the cross asset, require free liquidity in the receive custody.
9. Transfer settlement to the user.
10. Release locked backing.
11. Subtract the transferred token amount from the custody that pays.
12. Reduce position size, collateral, and locked amount.

Decrease liquidity check by case:

1. Decrease long, receive SOL: checks payout is bounded by released locked SOL.
2. Decrease long, receive USDC: checks free USDC.
3. Decrease short, receive USDC: checks payout is bounded by released locked USDC.
4. Decrease short, receive SOL: checks free SOL.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

add_collateral_perp.rs

Current flow:

1. Validate position, owner, pool, custodies, oracle accounts, funding account, and token accounts.
2. Calculate collateral value from selected payment asset.
3. Transfer collateral from user to custody.
4. Increase selected custody token_owned.
5. Increase position collateral fields.
6. Recalculate health values.

Liquidity check:

1. No pool payout happens.
2. No new locked backing is created.
3. No free-liquidity check is needed.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

remove_collateral_perp.rs

Current flow:

1. Validate position, owner, pool, custodies, oracle accounts, and token accounts.
2. Calculate removed collateral value.
3. Calculate new collateral and margin values.
4. Check new margin stays above liquidation margin plus buffer.
5. Check selected custody has token_owned - token_locked >= withdrawal_tokens.
6. Transfer withdrawal to the user.
7. Subtract withdrawn amount from selected custody token_owned.
8. Update position collateral fields.

Liquidity check:

1. The current check uses free liquidity, not total token_owned.
2. Collateral withdrawal does not release locked backing.
3. Correct logic should require receive_custody.token_owned - receive_custody.token_locked >= withdrawal_tokens.

Extra checks:

1. It checks leverage and margin health.
2. It includes a liquidation-margin buffer.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

liquidate_perp.rs

Current flow:

1. Validate position, liquidator, pool, custodies, oracle accounts, and token accounts.
2. Check the position is liquidatable.
3. Calculate owner settlement and liquidator reward as USD amounts.
4. Select the locked backing asset as payout asset: long pays SOL and short pays USDC.
5. Convert owner settlement and liquidator reward into locked backing tokens.
6. Require total payout is bounded by position.locked_amount.
7. Transfer owner settlement and liquidator reward from locked backing custody.
8. Subtract the transferred payout tokens from locked backing custody token_owned.
9. Release locked backing.
10. Mark position liquidated.
11. Update pool open interest.

Liquidity check:

1. These payouts come from locked backing custody.
2. Long liquidation pays SOL.
3. Short liquidation pays USDC.
4. Total payout must be less than or equal to released locked backing.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

update_borrow_fees.rs

Current flow:

1. Validate the perp position, pool, and relevant custody.
2. Check the position is not liquidated.
3. Calculate elapsed time since last borrow-fee update.
4. Calculate borrow fees from utilization and borrow rate.
5. Add fees to position accrued borrow fees.
6. Update borrow-fee timestamp and snapshot fields.

Liquidity check:

1. No pool payout happens.
2. No lock is created or released.
3. No free-liquidity check is needed.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

manage_tp_sl_orders.rs

Current flow:

1. Validate the owner, orderbook, and target position.
2. Add, update, or remove take-profit and stop-loss orders.
3. Store trigger price, size percent, and receive asset.
4. Emit TP/SL order events.

Liquidity check:

1. No pool payout happens.
2. No lock is created or released.
3. No free-liquidity check is needed.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.

execute_tp_sl_order.rs Perp Branch

Current flow:

1. Validate TP/SL order and trigger condition.
2. Calculate closed perp size.
3. Calculate PnL, fees, and settlement.
4. Convert settlement into selected receive asset.
5. Check same-asset payout against released locked backing or cross-asset payout against free liquidity.
6. Transfer settlement to the user.
7. Release locked backing.
8. Subtract the transferred settlement tokens from the custody that pays.
9. Reduce or close the perp position.

Liquidity check by case:

1. Perp long TP/SL, receive SOL: checks payout is bounded by released locked SOL.
2. Perp long TP/SL, receive USDC: checks free USDC.
3. Perp short TP/SL, receive USDC: checks payout is bounded by released locked USDC.
4. Perp short TP/SL, receive SOL: checks free SOL.

To-do / extra edits:

1. This has been perfected and there is nothing left to do.