Message: ExecuteLiquidityOrder

This operation allows to execute a liquidity order. The message sender must be an allowlisted executor.

The message must carry enough TON to pay for the estimated gas fees, which vary depending on whether the order is to increase the LP position (needing to send one mint message to mint LP jettons) or decrease the position (needing to send one burn message to burn LP jettons and one transfer message to transfer the underlying asset jetton back to the owner).

The message contains a map of asset prices, which is used to compute the updated global PNL. This map is not validated in any way, and the executor is trusted to provide accurate prices for all the assets in which the pool has an open position.

Next, funding and rollover fees are charged and credited to the protocol owners and LPs, increasing the globalLPFund and protocolTradingFee storage variables. The values by which the fees are increased are controlled by the message sender and are not validated in any way.

Finally, the order is executed, with varying actions depending on whether the order was to increase or decrease the LP position.

Orders to increase the LP position require minting new LP tokens representing the position. The contract asserts that the amount of assets managed by the pool after the mint would not exceed the configured maxLpNetCap. If the total amount surpasses the configured threshold, execution reverts, not canceling the order and not returning the deposited jettons. The jettons are not lost, since the user can cancel the order after a lock period. Next, the LP jettons representing the position are minted to the user posting the order. The amount of LP jettons is computed proportionally, as the amount of asset jettons deposited by the user multiplied by the ratio between the total asset jettons deposited and the total amount of LP jettons in circulation.

Orders to decrease the LP position require burning the LP jettons corresponding to the position being reduced and returning the asset jettons corresponding to the position-size decrease to the order owner. The amount of asset jettons returned to the user is the amount of burned LP jettons multiplied by the ratio between the amount of asset jettons managed by the pool divided by the total LP jetton supply in circulation.

Finally, the order is deleted from the contract storage, the execution fees are sent to the receiver (which can be specified in the message and defaults to the message sender otherwise), an event is emitted to aid off-chain observers detect the execution, and any excess TON is returned to the message sender.

Inputs

The incoming message has the following structure:

• orderId

  • Validation: Must refer to an existing nonpending order.

  • Impact: Identifies the order to be canceled.

• trxId

  • Validation: None.

  • Impact: Request ID to be used for the jetton transfer if the order is to decrease the position.

• executionFeeReceiver

  • Validation: None.

  • Impact: Optional address that will receive the execution-fees refund. If unspecified, defaults to the sender of the message.

• prices

  • Validation: None.

  • Impact: Map of asset prices — used to update the global PNL.

• lpFundingFeeGrowth

  • Validation: None.

  • Impact: Parameter used to charge funding fees.

• rolloverFeeGrowth

  • Validation: None.

  • Impact: Parameter used to charge rollover fees.

Test coverage

Intended branches

Negative behavior