Expiry Futures Smart Contracts

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

For expiry futures:

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

open_future.rs

Current flow:

1. Validate future parameters, owner, pool, custodies, oracle accounts, funding account, and token accounts.
2. Read current SOL and USDC prices.
3. Calculate position size and collateral value.
4. Calculate fixed interest rate.
5. Calculate locked_amount.
6. For a long, locked_amount is SOL backing.
7. For a short, locked_amount is USDC backing.
8. Check free liquidity in the locked custody.
9. Long checks sol_custody.token_owned - sol_custody.token_locked >= locked_amount.
10. Short checks usdc_custody.token_owned - usdc_custody.token_locked >= locked_amount.
11. Transfer user collateral into the selected collateral custody.
12. Increase collateral custody token_owned.
13. Increase locked custody token_locked.
14. Add fixed-rate exposure.
15. Store future state.

Liquidity check:

1. This file correctly checks free liquidity before creating a new lock.

To-do / extra edits:

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

open_limit_future.rs

Current flow:

1. Validate limit future parameters, owner, pool, custodies, oracle accounts, funding account, and token accounts.
2. Read prices.
3. Calculate future size, collateral, fixed rate, and future locked_amount.
4. Transfer user collateral into the selected collateral custody.
5. Increase collateral custody token_owned.
6. Store pending future state.
7. Do not increase token_locked.
8. Do not add fixed-rate exposure yet.

Liquidity check:

1. Current code does not check pool backing liquidity at placement.
2. Because the file does not lock liquidity at placement, backing liquidity is checked in execute_limit_future.rs.

To-do / extra edits:

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

execute_limit_future.rs

Current flow:

1. Validate the pending future and keeper/execution authority.
2. Check limit trigger conditions.
3. Set execution time and entry fields.
4. Calculate liquidation price.
5. Long execution checks sol_custody.token_owned - sol_custody.token_locked >= future.locked_amount.
6. Short execution checks usdc_custody.token_owned - usdc_custody.token_locked >= future.locked_amount.
7. Long execution increases sol_custody.token_locked by future.locked_amount.
8. Short execution increases usdc_custody.token_locked by future.locked_amount.
9. Add fixed-rate exposure.
10. Check sol_custody.token_locked <= sol_custody.token_owned.
11. Check usdc_custody.token_locked <= usdc_custody.token_owned.
12. Mark the limit future as executed.

Liquidity check:

1. This file checks free liquidity before increasing token_locked.
2. This is the correct file where execution-time free-liquidity validation belongs.
3. The file keeps a final post-lock solvency assertion.

To-do / extra edits:

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

close_future.rs

Current flow:

1. Validate the future, owner, close percentage, pool, custodies, oracle accounts, and token accounts.
2. Calculate closed size.
3. Calculate closed collateral amount.
4. Calculate locked_amount_to_release.
5. Calculate current PnL.
6. Calculate closing fee.
7. Calculate settlement_usd = collateral + PnL - fee, floored at zero.
8. Convert settlement_usd into the selected receive asset.
9. If the receive asset matches the locked backing asset, require settlement_tokens <= locked_amount_to_release.
10. If the receive asset is the cross asset, require receive_custody.token_owned - receive_custody.token_locked >= settlement_tokens.
11. Transfer settlement_tokens to the user.
12. Subtract settlement_tokens from selected receive custody token_owned.
13. Release locked backing.
14. Reduce or close the future.
15. Remove fixed-rate exposure.

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 subtracts settlement from selected custody.
2. 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_future.rs

Current flow:

1. This file delegates to cancel_limit_future.rs.
2. It maps close-limit-future parameters into cancel-limit-future parameters.

Liquidity check:

1. It inherits the refund behavior from cancel_limit_future.rs.

To-do / extra edits:

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

cancel_limit_future.rs

Current flow:

1. Validate pending future, owner, close percentage, 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 future.

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.

settle_expired_future.rs

Current flow:

1. Validate the expired future, settler, pool, custodies, oracle accounts, and token accounts.
2. Read final settlement price.
3. Mark the future expired.
4. Calculate final settlement amount and PnL.
5. Select the locked backing asset as settlement asset: long settles in SOL and short settles in USDC.
6. Require settlement payout is bounded by future.locked_amount.
7. Transfer settlement to the owner.
8. Subtract settlement from locked custody token_owned.
9. Release locked backing.
10. Mark the future settled.

Liquidity check by case:

1. Long settles in SOL and checks payout is bounded by released locked SOL.
2. Short settles in USDC and checks payout is bounded by released locked USDC.

To-do / extra edits:

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

add_collateral_future.rs

Current flow:

1. Validate the future, owner, pool, custodies, oracle accounts, funding account, and token accounts.
2. Calculate collateral value from selected payment asset.
3. Transfer user collateral into custody.
4. Increase selected custody token_owned.
5. Increase future 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_future.rs

Current flow:

1. Validate the future, owner, pool, custodies, oracle accounts, and token accounts.
2. Calculate withdrawn collateral value.
3. Calculate new collateral value.
4. Check minimum collateral requirement.
5. Check max leverage.
6. Check the position remains healthy.
7. Check selected custody has token_owned - token_locked >= requested_amount.
8. Transfer requested collateral amount to the user.
9. Subtract requested amount from selected custody token_owned.
10. Update future collateral fields.

Liquidity check:

1. Collateral withdrawal does not release locked backing.
2. Current code checks free liquidity before transfer.
3. The check is receive_custody.token_owned - receive_custody.token_locked >= withdrawal_amount.

Extra checks:

1. It checks minimum collateral.
2. It checks max leverage.
3. It checks the future remains healthy after withdrawal.

To-do / extra edits:

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

liquidate_future.rs

Current flow:

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

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.

execute_tp_sl_order.rs Future Branch

Current flow:

1. Validate TP/SL order and trigger condition.
2. Calculate closed future size and settlement.
3. Convert settlement into selected receive asset.
4. Check same-asset payout against released locked backing or cross-asset payout against free liquidity.
5. Transfer settlement to the user.
6. Release locked backing and remove fixed-rate exposure.
7. Reduce or close the future.

Liquidity check by case:

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

To-do / extra edits:

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