# 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 | *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ston.fi/developer-section/dex/smart-contracts/v1/pool.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.