Message: JettonTransferNotification

This message is sent by Jetton wallets to inform the pool of an incoming transfer. The message is rejected if the pool is in the stopped state.

The message must be sent by either the tlpWallet or the jettonWallet address.

If the sender is the jettonWallet, the message payload forward_payload field is read to determine which operation should be performed on the incoming assets, among the following:

• OP_CREATE_INCREASE_LP_POSITION_ORDER

• OP_CREATE_INCREASE_PERP_POSITION_ORDER

• OP_INCREASE_AUM

If the message is sent from the tlpWallet address, the operation is not read from the message forward_payload, but rather it is assumed that a new liquidity order should be created.

If the sender is not jettonWallet or tlpWallet or the operation is invalid, the incoming jettons are refunded and processing stops.

Inputs

The incoming message has the following structure:

• query_id

  • Validation: None.

  • Impact: Arbitrary request ID — does not affect the handler logic.

• amount

  • Validation: Must be sufficient to cover the fees required to execute the specified order.

  • Impact: Amount of jettons transferred.

• sender

  • Validation: Validation is operations-dependent — more details below.

  • Impact: Address of the sender of the jettons.

• forward_payload

  • Validation: Validation is operations-dependent — more details below.

  • Impact: Slice containing the operation to be performed.

Operation: OP_CREATE_INCREASE_LP_POSITION_ORDER

This operation requests the creation of an order to increase the LP position of the sender.

The operation payload also specifies an executionFee, which must be greater than the lpMinExecutionFee configured in the contract storage (otherwise the jettons are returned and processing stops).

The incoming message must have sufficient TON to cover the executionFee plus the createLiquidityOrderGas amount needed to cover gas expenses for creating the order (otherwise the jettons are refunded and processing stops).

The details of the order are stored in the contract storage, including the owner of the order (the owner of the incoming jettons), the amount of jettons associated with the order, the execution fee paid, and the time the order is inserted.

The order details will be retrieved from contract storage when the order is executed by an executor.

Operation: OP_CREATE_INCREASE_PERP_POSITION_ORDER

This operation requests the creation of an order to increase the perpetual position of the sender.

The operation payload includes the following parameters:

• marginDelta: The amount to be added to the position collateral.

• executionFee: The fee to be paid to the executor executing the order.

• isMarket: The boolean specifying whether this is a market or limit order.

• tokenId: The identifier of the asset for which the user wants to take a position in.

• isLong: The boolean specifying whether the user wants to take a long or short position.

• sizeDelta: The size of the order.

• triggerPrice: The trigger price, only relevant for limit orders (isMarket is false).

• requestTime: The arbitrary number specified by the user, intended to identify the time of the price point the user wants to use for the order. For off-chain entity use only.

The payload can also include optional take-profit/stop-loss conditions:

• tpSize: The size of the take-profit order.

• tpPrice: The price at which the take-profit condition triggers.

• slSize: The size of the stop-loss order.

• slPrice: The price at which the stop-loss condition triggers.

The incoming message must have sufficient TON to cover the executionFee plus the createPerpOrderGas amount configured in the contract storage, which is needed to cover the gas spent to create the order (the incoming jettons are returned, and processing stops otherwise).

The executionFee must be sufficient to cover the execution fee for the order plus the execution fee for one or two additional orders if the take-profit and/or stop-loss conditional orders are requested. If the executionFee is insufficient, the incoming jettons are refunded and processing stops.

The requested order is then persisted in the contract storage. Each order is assigned a unique incremental ID used to index the order details in the perpOrders map. An event is emitted to signal the order creation to off-chain observers.

If any take-profit/stop-loss conditions are requested, they are also recorded in the perpOrderExs map.

Finally, the totalExecutionFee available to be paid out to the executors is incremented by the order executionFee, and any excess TON is returned to the message sender.

Operation: OP_INCREASE_AUM

This operation can only be requested by the manager address. The operation increases the globalLPFund variable, which tracks the total amount of assets provided by the LPs plus the current unrealized PNL. The variable is increased by the amount received.

Test coverage

Intended branches

• OP_CREATE_INCREASE_LP_POSITION_ORDER

  Successfully create a new order to increase the LP position.

• OP_CREATE_INCREASE_PERP_POSITION_ORDER

  Successfully create a new order to increase the perpetual position.
  Successfully create a new order to increase the perpetual position with take-profit and stop-loss conditions.

• OP_INCREASE_AUM

  Successfully increase the AUM of the pool.

Negative behavior

• All opcodes

  Contract is stopped.
  Caller is not the tlpWallet or jettonWallet address.

• OP_CREATE_INCREASE_LP_POSITION_ORDER

  Insufficient execution fee is provided.
  Insufficient gas is provided.

• OP_CREATE_INCREASE_PERP_POSITION_ORDER

  Insufficient execution fee is provided.
  Insufficient gas is provided.

• OP_INCREASE_AUM

  Original caller is not the manager address.