# Pool (v1) ## Off-chain get methods ### `get_pool_data` Returns the current state of the pool: Jetton token reserves, Jetton wallet addresses and fee parameters. ``` (int, int, slice, slice, int, int, int, slice, int, int) get_pool_data() method_id; ``` #### **Arguments** `None` #### **Result** Returns current state of the `Pool` **Result structure** | Key | Type | Index | Description | | ------------------------------- | --------- | ----- | ---------------------------------------------------------------------------- | | `reserve0` | `coins` | 0 | Amount of the first token (in basic token units) | | `reserve1` | `coins` | 1 | Amount of the second token (in basic token units) | | `token0_wallet_address` | `address` | 2 | Address of the first Jetton token | | `token1_wallet_address` | `address` | 3 | Address of the second Jetton token | | `lp_fee` | `uint8` | 4 | Liquidity pool fee value | | `protocol_fee` | `uint8` | 5 | Protocol fee | | `ref_fee` | `uint8` | 6 | Referrer fee | | `protocol_fee_address` | `address` | 7 | Address for receiving protocol fees | | `collected_token0_protocol_fee` | `coins` | 8 | Amount of collected protocol fees of the first token (in basic token units) | | `collected_token1_protocol_fee` | `coins` | 9 | Amount of collected protocol fees of the second token (in basic token units) | Notes: * fee ratio is the value of fee divided by `FEE_DIVIDER` (10000); so a fee of 1% has a value of 100 ### `get_expected_outputs` Estimate expected result of the `amount` of `jettonWallet` tokens swapped to the other type of tokens of the pool. ``` (int, int, int) get_expected_outputs(int amount, slice token_wallet) method_id; ``` #### **Arguments** | Name | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------------- | | `amount` | `coins` | Amount of tokens to swap (in basic token units) | | `token_wallet` | `address` | Token Jetton address (must be equal to one of the Jetton addresses of the pool) | #### **Result** Returns expected result of a token swap **Result structure** | Key | Type | Index | Description | | ------------------- | ------- | ----- | ----------------------------------------------------------- | | `jetton_to_receive` | `coins` | 0 | Amount of tokens received (in basic token units) | | `protocol_fee_paid` | `coins` | 1 | Amount tokens paid for protocol fees (in basic token units) | | `ref_fee_paid` | `coins` | 2 | Amount tokens paid for referrer fees (in basic token units) | ### `get_expected_tokens` Estimate an expected amount of lp tokens minted when providing liquidity. ``` (int) get_expected_tokens(int amount0, int amount1) method_id; ``` #### **Arguments** | Key | Type | Description | | --------- | ------- | ------------------------------------------------------------- | | `amount0` | `coins` | Amount of tokens for the first Jetton (in basic token units) | | `amount1` | `coins` | Amount of tokens for the second Jetton (in basic token units) | #### **Result** Returns an estimated amount of liquidity tokens to be minted ### `get_expected_liquidity` Estimate expected liquidity freed upon burning liquidity tokens. ``` (int, int) get_expected_liquidity(int jetton_amount) method_id; ``` #### **Arguments** | Key | Type | Description | | --------------- | ------- | ------------------------------------------------- | | `jetton_amount` | `coins` | Amount of liquidity tokens (in basic token units) | #### **Result** Returns expected freed liquidity **Return structure** | Key | Type | Index | Description | | --------- | ------- | ----- | ------------------------------------------------------------- | | `amount0` | `coins` | 0 | Amount of tokens for the first Jetton (in basic token units) | | `amount1` | `coins` | 1 | Amount of tokens for the second Jetton (in basic token units) | ### `get_lp_account_address` Get the lp account address of a user ``` slice get_lp_account_address(slice owner_address) method_id; ``` #### **Arguments** | Key | Type | Description | | --------------- | --------- | ----------------- | | `owner_address` | `address` | Address of a user | #### **Result** Function the lp account address of a user ### `get_jetton_data` Standard jetton 'get' methods from TonWeb JettonMinter. ``` (int, int, slice, cell, cell) get_jetton_data() method_id; ``` #### **Arguments** None #### **Result** Returns a structure with Jetton data **Return structure** | Key | Type | Index | Description | | -------------------- | --------- | ----- | ----------------------------------------- | | `total_supply` | `coins` | 0 | Total token supply (in basic token units) | | `is_mintable` | `bool` | 1 | If new tokens can be minted | | `admin_address` | `address` | 2 | Admin address | | `jetton_content_uri` | `string` | 3 | Offchain uri with Jetton data | | `jetton_wallet_code` | `cell` | 4 | Code of the lp Jetton wallet | ### `get_wallet_address` Get lp wallet address of a user. ``` slice get_wallet_address(slice owner_address) method_id; ``` #### **Arguments** | Name | Type | Description | | --------------- | --------- | ----------------- | | `owner_address` | `address` | Address of a user | #### **Result** Returns calculated lp wallet address of a user ## On-chain queries On-chain counterparts of getter methods. #### **Operations table** | Name | Value | Description | | --------------------------- | ---------- | ------------------------------------------------------------------------------------- | | `getter_pool_data` | 0x43c034e6 | Sends a message with the current state of the pool | | `getter_expected_outputs` | 0xed4d8b67 | Sends a message with an estimated result of the token swap | | `getter_lp_account_address` | 0x9163a98a | Sends a message with the lp account address of a user | | `getter_expected_tokens` | 0x9ce632c5 | Sends a message with an estimated amount of lp tokens minted when providing liquidity | | `getter_expected_liquidity` | 0x8751801f | Sends a message with estimated liquidity freed upon burning of liquidity tokens | | `provide_wallet_address` | 0x2c76b973 | Sends a message with the lp wallet address of a user | ### `getter_pool_data` (0x43c034e6) Sends a message with the current state of the pool. On-chain equivalent of `get_pool_data`. #### **TL-B** ``` getter_pool_data#43c034e6 query_id:uint64 = InternalMsgBody; ``` #### **Message body** None #### **Outgoing messages** Sends a message with current pool data to the `sender_address` #### **Response message body** | Name | Type | Description | | ---------------- | --------- | ------------------------------------------------- | | `op` | `uint32` | Operation code is equal to `getter_pool_data` | | `query_id` | `uint64` | Query id | | `reserve0` | `coins` | Amount of the first token (in basic token units) | | `reserve1` | `coins` | Amount of the second token (in basic token units) | | `token0_address` | `address` | Address of the first Jetton token | | `token1_address` | `address` | Address of the second Jetton token | | `ref_fee_data` | `cell` | Cell with fee data | #### **`ref_fee_data` body** | Name | Type | Description | | ------------------------------- | --------- | ---------------------------------------------------------------------------- | | `lp_fee` | `uint8` | Liquidity pool fee value | | `protocol_fee` | `uint8` | Protocol fee | | `ref_fee` | `uint8` | Referrer fee | | `protocol_fee_address` | `address` | Address for receiving protocol fees | | `collected_token0_protocol_fee` | `coins` | Amount of collected protocol fees of the first token (in basic token units) | | `collected_token1_protocol_fee` | `coins` | Amount of collected protocol fees of the second token (in basic token units) | ### `getter_expected_outputs` (0xed4d8b67) Sends a message with an estimated result of the token swap. On-chain equivalent of `get_expected_outputs`. #### **TL-B** ``` getter_expected_outputs#ed4d8b67 query_id:uint64 amount:Grams token_wallet:MsgAddress = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | -------------- | --------- | --------------------------------------- | | `amount` | `coins` | Amount of tokens (in basic token units) | | `token_wallet` | `address` | Token Jetton address | #### **Outgoing messages** Sends a message with an estimated result of the token swap to `sender_address` #### **Response message body** | Name | Type | Description | | ------------------ | -------- | ----------------------------------------------------------- | | `op` | `uint32` | Operation code is equal to `getter_expected_outputs` | | `query_id` | `uint64` | Query id | | `out` | `coins` | Amount of tokens to be received (in basic token units) | | `protocol_fee_out` | `coins` | Amount tokens paid for protocol fees (in basic token units) | | `ref_fee_out` | `coins` | Amount tokens paid for referrer fees (in basic token units) | ### `getter_lp_account_address` (0x9163a98a) Sends a message with the lp account address of a user. On-chain equivalent of `get_lp_account_address`. #### **TL-B** ``` getter_lp_account_address#9163a98a query_id:uint64 user_address:MsgAddress = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | -------------- | --------- | ----------------- | | `user_address` | `address` | Address of a user | #### **Outgoing messages** Sends a message with the lp account address of a user to `sender_address` #### **Response message body** | Name | Type | Description | | -------------------- | --------- | ---------------------------------------------------- | | `op` | `uint32` | Operation code is equal to `getter_expected_outputs` | | `query_id` | `uint64` | Query id | | `lp_account_address` | `address` | lp account address of a user | Notes: * the current version of the contract returns a message with `getter_expected_outputs` op code instead of `getter_lp_account_address` so the user must differentiate those messages with some other means ### `getter_expected_tokens` (0x9ce632c5) Sends a message with an estimated amount of lp tokens minted when providing liquidity. On-chain equivalent of `get_expected_tokens` #### **TL-B** ``` getter_expected_tokens#9ce632c5 query_id:uint64 user_address:MsgAddress amount0:Grams amount1:Grams = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | -------------- | --------- | ------------------------------------------------------------- | | `user_address` | `address` | User address (unused) | | `amount0` | `coins` | Amount of tokens for the first Jetton (in basic token units) | | `amount1` | `coins` | Amount of tokens for the second Jetton (in basic token units) | #### **Outgoing messages** Sends a message with an estimated amount of liquidity tokens to be minted to `sender_address` #### **Response message body** | Name | Type | Description | | ----------- | -------- | ---------------------------------------------------------- | | `op` | `uint32` | Operation code is equal to `getter_expected_tokens` | | `query_id` | `uint64` | Query id | | `liquidity` | `coins` | Expected amount of liquidity tokens (in basic token units) | ### `getter_expected_liquidity` (0x8751801f) Sends a message with estimated liquidity freed upon burning liquidity tokens. On-chain equivalent of `get_expected_liquidity`. #### **TL-B** ``` getter_expected_liquidity#8751801f query_id:uint64 jetton_amount:Grams = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | --------------- | ------- | --------------------------------------------------------- | | `jetton_amount` | `coins` | Amount of liquidity tokens to burn (in basic token units) | #### **Outgoing messages** Sends a message with estimated liquidity to `sender_address` #### **Response message body** | Name | Type | Description | | ------------- | -------- | ------------------------------------------------------------- | | `op` | `uint32` | Operation code is equal to `getter_expected_tokens` | | `query_id` | `uint64` | Query id | | `amount0_out` | `coins` | Amount of tokens for the first Jetton (in basic token units) | | `amount1_out` | `coins` | Amount of tokens for the second Jetton (in basic token units) | ### `provide_wallet_address` (0x2c76b973) Sends a message with the lp wallet address of a user. On-chain equivalent of `get_wallet_address`. #### **TL-B** ``` provide_wallet_address#2c76b973 query_id:uint64 owner_address:MsgAddress include_address?:Bool = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ------------------ | --------- | -------------------------------------------- | | `owner_address` | `address` | Address of a user | | `include_address?` | `uint1` | Include user address in the response message | #### **Outgoing messages** Sends a message back to sender with the calculated lp wallet address of a user #### **Response message body** | Name | Type | Description | | ------------------- | -------------- | ------------------------------------------------------------- | | `op` | `uint32` | Operation code is equal to `take_wallet_address` (0xd1735400) | | `query_id` | `uint64` | Query id | | `lp_wallet_address` | `address` | Calculated lp wallet address | | `ref_address` | `cell \| null` | Cell with data if `include_address?` evaluates to `true` | #### **`ref_address` body** | Name | Type | Description | | ------------------ | --------- | ----------------- | | `included_address` | `address` | Address of a user | ## Jetton handlers Handles operations sent from a Jetton wallet. #### **Operations table** | Name | Value | Description | | ------------------- | ---------- | --------------------------------------------------------------- | | `burn_notification` | 0x7bdd97de | Sent by LP wallet after burning LP jettons to release liquidity | ### `burn_notification` (0x7bdd97de) Sent by LP wallet after burning LP jettons to release liquidity. #### **TL-B** ``` burn_notification#7bdd97de query_id:uint64 jetton_amount:Grams from_address:MsgAddress response_address:MsgAddress = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ------------------ | --------- | --------------------------------------------------------- | | `jetton_amount` | `coins` | Amount of liquidity tokens to burn (in basic token units) | | `from_address` | `address` | User address | | `response_address` | `address` | Address for a response message | #### **Outgoing messages** Sends a message with op `excesses` (0xd53276db) to `response_address` Sends a message with a released amount of both tokens to be received by a user as a result of the burn operation to the router, which initiates `pay_to` operation to `from_address` ## Router internal message handlers Handles messages from the router. #### **Operations table** | Name | Value | Description | | -------------- | ---------- | ---------------------- | | `swap` | 0x25938561 | Swap tokens | | `provide_lp` | 0xfcf9e58f | Provide liquidity | | `reset_gas` | 0x42a0fb43 | Reset gas | | `collect_fees` | 0x1fcb7d3d | Collect fees | | `set_fees` | 0x355423e5 | Set new fee parameters | ### `swap` (0x25938561) Swap tokens. This message is received from the router when the user initiates a token swap. #### **TL-B** ``` ref_bodycell$_ from_real_user:MsgAddress ref_address:MsgAddress = RefBodyCell; swap#25938561 query_id:uint64 from_user:MsgAddress token_wallet:MsgAddress amount:Grams min_out:Grams ref_bodycell:(Either RefBodyCell ^RefBodyCell) = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ------------------- | --------- | -------------------------------------------------------- | | `from_user_address` | `address` | User address | | `token_wallet` | `address` | Incoming Jetton wallet address | | `amount` | `coins` | Amount of incoming tokens (in basic token units) | | `min_out` | `coins` | Minimum amount of received tokens (in basic token units) | | `has_ref` | `uint1` | If referral is present | | `ref_bodycell` | `cell` | Cell with data | Notes: * swap will fail if a user should receive less than `min_out` of tokens as a result #### **`ref_bodycell` body** | Name | Type | Description | | ---------------- | --------- | ----------------------------------------------- | | `from_real_user` | `address` | Who initialized the swap | | `ref_address` | `address` | Referral address; present only if has\_ref is 1 | #### **Outgoing messages** Sends a message with an amount of the other tokens to be received by a user as a result of the swap to the router, which initiates `pay_to` operation Additionally may send a message with referrer fees to the router, which initiates `pay_to` operation to `ref_address` ### `provide_lp` (0xfcf9e58f) Provide liquidity for the pool. A user must submit an amount of both tokens to receive lp tokens and add new liquidity to a pool. This message is routed to liquidity pool account with `add_liquidity` operation code. #### **TL-B** ``` provide_lp#fcf9e58f query_id:uint64 owner_addr:MsgAddress min_lp_out:Grams amount0:Grams amount1:Grams = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ------------ | --------- | ------------------------------------------------------------------ | | `owner_addr` | `address` | User address | | `min_lp_out` | `coins` | Minimum amount of received liquidity tokens (in basic token units) | | `amount0` | `coins` | Amount of the first Jetton token (in basic token units) | | `amount1` | `coins` | Amount of the second Jetton token (in basic token units) | #### **Outgoing messages** Sends a message to liquidity pool account with `add_liquidity` operation code. ### `reset_gas` (0x42a0fb43) Updates the amount of $TON (in nanoTons) on the pool to `REQUIRED_TON_RESERVE` (10000000) of the pool. The remaining amount of $TON will be sent back to the router. #### **TL-B** ``` reset_gas#42a0fb43 query_id:uint64 = InternalMsgBody; ``` #### **Message body** None #### **Outgoing messages** Sends an empty message back to the router with the remaining $TON ### `collect_fees` (0x1fcb7d3d) Collect protocol fees which will be sent to `protocol_fee_address`. A user which initiates this operation receives a bounty equal to 1/1000 of collected amount of both tokens. #### **TL-B** ``` collect_fees#1fcb7d3d query_id:uint64 = InternalMsgBody; ``` #### **Message body** None #### **Outgoing messages** Sends a message with collected fees (minus the bounty) to `protocol_fee_address` Sends a message with an amount of tokens to be received by a user as a bounty (equal to collected fees divided by 1000) to the router, which initiates `pay_to` operation ### `set_fees` (0x355423e5) Set new fee values including liquidity pool fees, protocol fees and referrer fees as well as an address for receiving collected protocol fees. #### **TL-B** ``` set_fees#355423e5 query_id:uint64 new_lp_fee:uint8 new_protocol_fee:uint8 new_ref_fee:uint8 new_protocol_fee_address:MsgAddress = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | -------------------------- | --------- | ---------------------------------------------------------- | | `new_lp_fee` | `uint8` | New liquidity pool fee ratio (multiplied by `FEE_DIVIDER`) | | `new_protocol_fee` | `uint8` | New protocol fee ratio (multiplied by `FEE_DIVIDER`) | | `new_ref_fee` | `uint8` | New referrer fee ratio (multiplied by `FEE_DIVIDER`) | | `new_protocol_fee_address` | `address` | Address for receiving protocol fees | Notes: * fee ratio is the value of fee divided by `FEE_DIVIDER` (10000); so to set a fee to 1% the value must be 100 * fees must be between `MIN_FEE` (0) and `MAX_FEE` (100) #### **Outgoing messages** None *** ## LP Account internal message handlers Handles messages from an lp account. #### **Operations table** | Name | Value | Description | | ------------------ | ---------- | ------------------------------------------------- | | `cb_add_liquidity` | 0x56dfeb8a | Sent by user's lp\_account after adding liquidity | | `cb_refund_me` | 0x89446a42 | Sent by user's lp\_account after adding liquidity | ### `cb_add_liquidity` (0x56dfeb8a) Add new liquidity to the pool. Sent by user's lp account after an appropriate amount (greater than `1000`) of both Jetton tokens is sent by a user. The resulting added liquidity must be greater than `min_lp_out` for the operation to be successful. #### **TL-B** ``` cb_add_liquidity#56dfeb8a query_id:uint64 tot_am0:Grams tot_am1:Grams user_address:MsgAddress min_lp_out:Grams = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | -------------- | --------- | ------------------------------------------------------------------ | | `tot_am0` | `coins` | Amount of the first Jetton token (in basic token units) | | `tot_am1` | `coins` | Amount of the second Jetton token (in basic token units) | | `user_address` | `address` | User address | | `min_lp_out` | `coins` | Minimum amount of received liquidity tokens (in basic token units) | Notes: * addition of liquidity will fail if a user should receive less than `min_lp_out` of lp tokens as a result * cannot add liquidity if a supply of either tokens becomes greater than `MAX_COINS` (2^120 - 1) #### **Outgoing messages** Sends a message with `internal_transfer` (0x178d4519) op code to the lp wallet of `user_address` with minted liquidity tokens; on initial liquidity addition tokens are minted to `addr_none` ### `cb_refund_me` (0x89446a42) Sent by user's lp account after a user initiates `refund_me` operation to cancel addition of new liquidity. The amount of previously stored tokens will be sent back to the user. #### **TL-B** ``` cb_refund_me#89446a42 query_id:uint64 tot_am0:Grams tot_am1:Grams user_address:MsgAddress = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | -------------- | --------- | -------------------------------------------------------- | | `tot_am0` | `coins` | Amount of the first Jetton token (in basic token units) | | `tot_am1` | `coins` | Amount of the second Jetton token (in basic token units) | | `user_address` | `address` | User address | #### **Outgoing messages** Sends a message with `tot_am0` of the first token and `tot_am1` of the second token to the router, which initiates `pay_to` operation *** ## User message handlers Handles direct messages from a user. #### **Operations table** | Name | Value | Description | | -------------- | ---------- | ------------------------------------------------------------ | | `collect_fees` | 0x1fcb7d3d | Called by anyone; collect fees; the caller receives a bounty | ### `collect_fees` (0x1fcb7d3d) Collect protocol fees which will be sent to `protocol_fee_address`. A user which initiates this operation receives a bounty equal to 1/1000 of collected amount of both tokens. #### **TL-B** ``` collect_fees#1fcb7d3d query_id:uint64 = InternalMsgBody; ``` #### **Message body** None #### **Outgoing messages** Sends a message with collected fees (minus the bounty) to `protocol_fee_address` Sends a message with an amount of tokens to be received by a user as a bounty (equal to collected fees divided by 1000) to the router, which initiates `pay_to` operation *** ## Constants | Name | Value | Description | | ----------------------------- | --------- | ------------------------------------------------------------------- | | `WORKCHAIN` | 0 | Workchain id | | `REQUIRED_TON_RESERVE` | 10000000 | Amount of $TON (in nanoTons) to be left on the pool contract as gas | | `REQUIRED_MIN_LIQUIDITY` | 1000 | Minimum amount of liquidity required | | `REQUIRED_MIN_COLLECT_FEES` | 1000000 | Minimum amount of tokens (in basic token units) collected as fees | | `MAX_COINS` | 2^120 - 1 | Maximum amount of tokens (in basic token units) stored as liquidity | | `PROVIDE_ADD_GAS_CONSUMPTION` | 10000000 | Additional gas (in nanoTons) for providing a wallet | | `FEE_DIVIDER` | 10000 | Fee values are divided by this value | | `MIN_FEE` | 0 | Minimum fee allowed | | `MAX_FEE` | 100 | Maximum fee allowed | ***