# LpAccount (v2)

## Off-chain get methods

### `get_lp_account_data`

Returns current state of the `LpAccount`.

```
(slice, slice, int, int) get_lp_account_data() method_id;
```

#### **Arguments**

None

#### **Result**

Returns `LpAccountData` structure containing current state of the lp account.

**`LpAccountData` structure**

| Key            | Type      | Index | Description                                               |
| -------------- | --------- | ----- | --------------------------------------------------------- |
| `user_address` | `address` | 0     | Owner's address                                           |
| `pool_address` | `address` | 1     | Pool's address                                            |
| `amount0`      | `coins`   | 2     | Balance of the first Jetton token (in basic token units)  |
| `amount1`      | `coins`   | 3     | Balance of the second Jetton token (in basic token units) |

## On-chain queries

On-chain counterparts of getter methods.

#### **Operations table**

| Name                     | Value      | Description                                        |
| ------------------------ | ---------- | -------------------------------------------------- |
| `getter_lp_account_data` | 0x24cfc100 | Sends a message with the current state of the pool |

### `getter_lp_account_data` (0x24cfc100)

Sends a message with current state of the lp account. On-chain equivalent of `get_lp_account_data`.

#### **TL-B**

```
getter_lp_account_data#24cfc100 query_id:uint64 = InternalMsgBody;
```

#### **Message body**

None

#### **Outgoing messages**

Sends a message with current state of the lp account to `sender_address`

#### **Response message body**

| Name           | Type      | Description                                               |
| -------------- | --------- | --------------------------------------------------------- |
| `op`           | `uint32`  | Operation code equal to `getter_lp_account_data`          |
| `query_id`     | `uint64`  | Query id                                                  |
| `user_address` | `address` | Owner's address                                           |
| `pool_address` | `address` | Pool's address                                            |
| `amount0`      | `coins`   | Balance of the first Jetton token (in basic token units)  |
| `amount1`      | `coins`   | Balance of the second Jetton token (in basic token units) |

## Pool message handlers

Handles incoming messages from a pool

#### **Operations table**

| Name            | Value      | Description   |
| --------------- | ---------- | ------------- |
| `add_liquidity` | 0x50c6a654 | Add liquidity |

### `add_liquidity` (0x50c6a654)

Stores the sent amount of tokens by the user to be added as new liquidity. Upon receiving an appropriate amount of both tokens sends a message with those amounts to a pool to be added as new liquidity. The automatic liquidity addition happens only if the amount of both tokens if greater than 1000 and non-zero `min_lp_out` was specified, otherwise the user can keep increasing the amount of stored tokens.

#### **TL-B**

```
add_liquidity#50c6a654 query_id:uint64 new_amount0:Coins new_amount1:Coins min_lp_out:Coins fwd_amount:Coins both_positive:uint1 to_user:MsgAddress custom_payload_cs:(Maybe ^Cell) additional_fields:^[refund_address:MsgAddress excess_address:MsgAddress] = InternalMsgBody;
```

#### **Message body**

| Name                | Type        | Description                                                                          |
| ------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `new_amount0`       | `coins`     | Amount of the first Jetton tokens added (in basic token units)                       |
| `new_amount1`       | `coins`     | Amount of the second Jetton tokens added (in basic token units)                      |
| `min_lp_out`        | `coins`     | Minimum required amount of received new liquidity tokens (in basic token units)      |
| `fwd_amount`        | `coins`     | Forward amount used to send `custom_payload` (if present) in `transfer_notification` |
| `both_positive`     | `uint1`     | Trigger liquidity deposit only if both token amounts are non-zero                    |
| `to_address`        | `address`   | Owner of new liquidity tokens                                                        |
| `custom_payload`    | `maybe_ref` | Payload sent in `transfer_notification` upon receiving tokens                        |
| `additional_fields` | `ref`       | See table below                                                                      |

#### **additional\_fields**

| Name             | Type      | Description                                                                                           |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `refund_address` | `address` | Address of the owner of `LpAccount` where tokens will be refunded if liquidity mint wasn't successful |
| `excess_address` | `address` | Address where all TON excesses will be sent                                                           |

Notes:

* addition of liquidity will fail if a user should receive less than `min_lp_out` of lp tokens as a result

#### **Outgoing messages**

Sends a message to the pool with `cb_add_liquidity` op

#### **Response message body**

| Name              | Type        | Description                                                                          |
| ----------------- | ----------- | ------------------------------------------------------------------------------------ |
| `op`              | `uint32`    | Operation code, equal to `cb_add_liquidity`                                          |
| `query_id`        | `uint64`    | Query id                                                                             |
| `amount0`         | `coins`     | Amount of the first Jetton tokens added (in basic token units)                       |
| `amount1`         | `coins`     | Amount of the second Jetton tokens added (in basic token units)                      |
| `user_address`    | `address`   | Owner's address                                                                      |
| `min_lp_out`      | `coins`     | Minimum amount of received liquidity tokens (in basic token units)                   |
| `fwd_amount`      | `coins`     | Forward amount used to send `custom_payload` (if present) in `transfer_notification` |
| `custom_payload`  | `maybe_ref` | Payload sent in `transfer_notification` upon receiving tokens                        |
| `additional_data` | `ref`       | See table below                                                                      |

#### **additional\_data**

| Name             | Type      | Description                                                                                           |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `to_address`     | `address` | Owner of new liquidity tokens                                                                         |
| `refund_address` | `address` | Address of the owner of `LpAccount` where tokens will be refunded if liquidity mint wasn't successful |
| `excess_address` | `address` | Address where all TON excesses will be sent                                                           |

Notes:

* addition of liquidity will fail if a user should receive less than `min_lp_out` of lp tokens as a result
* `LpAccount` is deleted upon sending this message (`Pool` always sends msgs with `state_init`)

## User message handlers

Handles incoming messages from a user

#### **Operations table**

| Name                   | Value      | Description                                                                                              |
| ---------------------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| `refund_me`            | 0x132b9a2c | Return previously sent tokens back to the user                                                           |
| `direct_add_liquidity` | 0x0ff8bfc6 | Directly add liquidity with specified amount of tokens and a minimum amount of received liquidity tokens |
| `reset_gas`            | 0x29d22935 | Reset gas                                                                                                |

### `refund_me` (0x132b9a2c)

Initiates a refund of stored tokens by `add_liquidity` if the user decides to cancel the addition of new liquidity. The amount of stored tokens will be sent to the pool which will initiate a transfer back to the user.

#### **TL-B**

```
refund_me#132b9a2c query_id:uint64 left_maybe_payload:(Maybe ^Cell) right_maybe_payload:(Maybe ^Cell) = InternalMsgBody;
```

#### **Message body**

None

#### **Outgoing messages**

Sends a message with `cb_refund_me` op code and amount of stored tokens to a pool. The pool will send a message to refund those tokens back to the user.

#### **Response message body**

| Name           | Type        | Description                                               |
| -------------- | ----------- | --------------------------------------------------------- |
| `op`           | `uint32`    | Operation code                                            |
| `query_id`     | `uint64`    | Query id                                                  |
| `amount0`      | `coins`     | Amount of the first Jetton tokens (in basic token units)  |
| `amount1`      | `coins`     | Amount of the second Jetton tokens (in basic token units) |
| `user_address` | `address`   | Owner's address                                           |
| `payload_0`    | `maybe_ref` | Payload used for `amount0`; can be `cross_swap`           |
| `payload_1`    | `maybe_ref` | Payload used for `amount1`; can be `cross_swap`           |

### `direct_add_liquidity` (0x0ff8bfc6)

Initiates an addition of new liquidity to a pool with a specified amount of both tokens and a minimum amount of received liquidity. The operation is successful only if there's an equal or greater amount of both tokens stored in the account (the amount of both tokens must be greater than 1000). This method is useful if an automatic liquidity addition has not been triggered upon deposition of tokens.

#### **TL-B**

```
direct_add_liquidity#ff8bfc6 query_id:uint64 am0:Coins am1:Coins min_lp_out:Coins fwd_amount:Coins to_user:MsgAddress custom_payload_cs:(Maybe ^Cell) additional_fields:^[refund_address:MsgAddress excess_address:MsgAddress] = InternalMsgBody;
```

#### **Message body**

| Name                | Type        | Description                                                                          |
| ------------------- | ----------- | ------------------------------------------------------------------------------------ |
| `amount0`           | `coins`     | Amount of the first Jetton tokens (in basic token units)                             |
| `amount1`           | `coins`     | Amount of the second Jetton tokens (in basic token units)                            |
| `min_lp_out`        | `coins`     | Minimum amount of received liquidity tokens (in basic token units)                   |
| `fwd_amount`        | `coins`     | Forward amount used to send `custom_payload` (if present) in `transfer_notification` |
| `to_address`        | `address`   | Owner of new liquidity tokens                                                        |
| `custom_payload`    | `maybe_ref` | Payload sent in `transfer_notification` upon receiving tokens                        |
| `additional_fields` | `ref`       | See table below                                                                      |

#### **additional\_data**

| Name             | Type      | Description                                                                                           |
| ---------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `refund_address` | `address` | Address of the owner of `LpAccount` where tokens will be refunded if liquidity mint wasn't successful |
| `excess_address` | `address` | Address where all TON excesses will be sent                                                           |

Notes:

* addition of liquidity will fail if a user should receive less than `min_lp_out` of lp tokens as a result
* `min_lp_out` value must be greater than zero for this operation to proceed

#### **Outgoing messages**

Sends a message with `cb_add_liquidity` op code and amount of both tokens to be added as new liquidity.

### `reset_gas` (0x29d22935)

Updates the amount of TON (in nanoTons) on the lp account to `storage_fee::lp_account` (10000000) of the account. The remaining TON will be sent back to the `user_address`

#### **TL-B**

```
reset_gas#29d22935 query_id:uint64 = InternalMsgBody;
```

#### **Message body**

None

#### **Outgoing messages**

Sends an empty message back to the user with the remaining TON

## Constants

| Name                      | Value   | Description                                                              |
| ------------------------- | ------- | ------------------------------------------------------------------------ |
| `storage_fee::lp_account` | 1000000 | Amount of TON (in nanoTons) to be left on the lp account contract as gas |