# Pool (v2) ## Off-chain get methods ### `get_pool_data` Returns the current state of the `Pool` ``` _ get_pool_data() method_id; ``` #### **Arguments** `None` #### **Result (common)** Returns `PoolData` structure containing current state of the pool. Typed pools may return additional arguments if present **`PoolData` structure** | Key | Type | Index | Description | | ------------------------------- | --------- | ----- | ---------------------------------------------------------------------------- | | `is_locked` | `bool` | 0 | true if `transfer_notification` operations are locked (`swap`, `provide_lp`) | | `router_address` | `address` | 1 | Address of the `Router` | | `total_supply` | `coins` | 2 | Total supply of lp tokens | | `reserve0` | `coins` | 3 | Amount of the first token (in basic token units) | | `reserve1` | `coins` | 4 | Amount of the second token (in basic token units) | | `token0_wallet_address` | `address` | 5 | Address of the first Jetton token | | `token1_wallet_address` | `address` | 6 | Address of the second Jetton token | | `lp_fee` | `uint16` | 7 | Liquidity pool fee value | | `protocol_fee` | `uint16` | 8 | Protocol fee | | `protocol_fee_address` | `address` | 9 | Address for receiving protocol fees | | `collected_token0_protocol_fee` | `coins` | 10 | Amount of collected protocol fees of the first token (in basic token units) | | `collected_token1_protocol_fee` | `coins` | 11 | Amount of collected protocol fees of the second token (in basic token units) | Notes: * fee ratio is the value of fee divided by `params::fee_divider` (10000); so a fee of 1% has a value of 100 #### **Result (`stableswap`)** Additional data in `PoolData` structure specific to stableswap pools **`PoolData` structure additional params** | Key | Type | Index | Description | | ----- | -------- | ----- | ---------------------------------- | | `amp` | `uint32` | 12 | Stableswap amplification parameter | #### **Result (`weighted_stableswap`)** Additional data in `PoolData` structure specific to weighted stableswap pools **`PoolData` structure additional params** | Key | Type | Index | Description | | ------------- | --------- | ----- | ------------------------------------------- | | `amp` | `uint128` | 12 | Weighted stableswap amplification parameter | | `rate` | `uint128` | 13 | Stable token ratio parameter | | `w0` | `uint128` | 14 | Token 0 weight parameter | | `rate_setter` | `address` | 15 | Address with rights to change `rate` | #### **Result (`weighted_const_product`)** Additional data in `PoolData` structure specific to weighted constant product pools **`PoolData` structure additional params** | Key | Type | Index | Description | | ---- | --------- | ----- | ------------------------ | | `w0` | `uint128` | 12 | Token 0 weight parameter | ### `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** Returns 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 **`JettonData` structure** | Key | Type | Index | Description | | -------------------- | --------- | ----- | ------------------------------------------------------ | | `total_supply` | `coins` | 0 | Total token supply of lp tokens (in basic token units) | | `mintable` | `bool` | 1 | always `true` | | `admin_address` | `address` | 2 | `Router` 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 a calculated lp wallet address of a user ### `get_pool_type` Get `Pool` type, equals to `dex_type` param in `get_router_data` ``` _ get_pool_type() method_id; ``` #### **Arguments** None #### **Result** Return pool type of this pool as string: * `constant_product` * `stableswap` * `weighted_stableswap` * `weighted_const_product` ## On-chain queries On-chain counterparts of getter methods. #### **Operations table** | Name | Value | Description | | --------------------------- | ---------- | ----------------------------------------------------- | | `getter_pool_data` | 0x26df39fc | Sends a message with the current state of the pool | | `getter_lp_account_address` | 0x15fbca95 | Sends a message with the lp account address of a user | | `provide_wallet_address` | 0x2c76b973 | Sends a message with the lp wallet address of a user | ### `getter_pool_data` (0x26df39fc) Sends a message with the current state of the pool. On-chain equivalent of `get_pool_data`. #### **TL-B** ``` getter_pool_data#26df39fc 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 | | `is_locked` | `uint1` | If this `Pool` is locked | | `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 | | `additional_data` | `cell` | Cell with additional data | #### **`additional_data` body** | Name | Type | Description | | ------------------------------- | --------- | ---------------------------------------------------------------------------- | | `lp_fee` | `uint16` | Liquidity pool fee value | | `protocol_fee` | `uint16` | Protocol fee | | `router_address` | `address` | Address of the `Router` | | `protocol_fee_address` | `address` | Address for receiving protocol fees | | `total_supply` | `coins` | Total amount of minted lp tokens | | `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_lp_account_address` (0x15fbca95) 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#15fbca95 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 | ### `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 | | `additional_data` | `maybe_ref` | Cell with data if `include_address?` evaluates to `true` | #### **`additional_data` 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_ext` | 0x297437cf | Sent by LP wallet after burning LP jettons to release liquidity | ### `burn_notification_ext` (0x297437cf) Sent by `LpWallet` after burning LP jettons to release liquidity. #### **TL-B** ``` burn_notification_ext#297437cf query_id:uint64 jetton_amount:Coins from_address:MsgAddress response_address:MsgAddress maybe_custom_payload:(Maybe ^Cell) = 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 | | `custom_payloads` | `maybe_ref` | Payloads for token0 and token1 | #### **custom\_payloads** | Name | Type | Description | | ----------- | ----------- | ----------------------------------------------- | | `payload_1` | `maybe_ref` | Payload used for `amount0`; can be `cross_swap` | | `payload_2` | `maybe_ref` | Payload used for `amount1`; can be `cross_swap` | #### **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` | 0x6664de2a | Swap tokens | | `provide_lp` | 0x37c096df | Provide liquidity | | `reset_gas` | 0x29d22935 | Reset gas | | `set_fees` | 0x58274069 | Set new fee parameters | ### `swap` (0x6664de2a) Swap tokens. This message is received from the router when the user initiates a token swap. #### **TL-B** ``` swap#6664de2a query_id:uint64 from_user:MsgAddress left_amount:Coins right_amount:Coins dex_payload:^[transferred_op:uint32 token_wallet1:MsgAddress refund_address:MsgAddress excesses_address:MsgAddress tx_deadline:uint64 swap_body:^[min_out:Coins receiver:MsgAddress fwd_gas:Coins custom_payload:(Maybe ^Cell) refund_fwd_gas:Coins refund_payload:(Maybe ^Cell) ref_fee:uint16 ref_address:MsgAddress]] = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ----------- | --------- | ------------------------------- | | `from_user` | `address` | User address | | `amount0` | `coins` | Amount of incoming first token | | `amount1` | `coins` | Amount of incoming second token | | `payload` | `cell` | Cell with dex payload | #### **`payload` body** | Name | Type | Description | | -------------------- | --------- | ----------------------------------------------- | | `op` | `uint32` | Swap op | | `other_token_wallet` | `address` | Address of the other `Router`token wallet | | `refund_address` | `address` | Address where refund will be sent if swap fails | | `excesses_address` | `address` | Address where TON excesses will be sent | | `additional_data` | `cell` | Cell with additional data | #### **`additional_data` body** | Name | Type | Description | | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------- | | `min_out` | `coins` | Minimum required amount of tokens to receive | | `receiver_address` | `address` | Address where tokens will be sent after swap | | `fwd_gas` | `coins` | Gas used to forward a message in `transfer_notification` after swap if `custom_payload` is present | | `custom_payload` | `maybe_ref` | Payload sent in `transfer_notification` after swap | | `refund_fwd_gas` | `coins` | Gas used to forward a message in `transfer_notification` if swap fails if `refund_payload` is present | | `refund_payload` | `maybe_ref` | Payload sent in `transfer_notification` if swap fails | | `ref_fee` | `uint16` | Referral fee | | `referral_address` | `address` | Referral address | Notes: * swap will fail if a user should receive less than `min_out` of tokens as a result * max allowed value of `ref_fee` is 100 (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_vault` operation to `Vault` of `referral_address` ### `provide_lp` (0x37c096df) 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#37c096df query_id:uint64 from_user:MsgAddress left_amount:Coins right_amount:Coins dex_payload:^[transferred_op:uint32 token_wallet1:MsgAddress refund_address:MsgAddress excesses_address:MsgAddress tx_deadline:uint64 provide_lp_body:^[min_lp_out:Coins to_address:MsgAddress both_positive:uint1 fwd_amount:Coins custom_payload:(Maybe ^Cell)]] = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ----------- | --------- | ------------------------------- | | `from_user` | `address` | User address | | `amount0` | `coins` | Amount of incoming first token | | `amount1` | `coins` | Amount of incoming second token | | `payload` | `cell` | Cell with dex payload | #### **`payload` body** | Name | Type | Description | | -------------------- | --------- | ----------------------------------------------- | | `op` | `uint32` | Provide lp op | | `other_token_wallet` | `address` | Address of the other `Router` token wallet | | `refund_address` | `address` | Address where refund will be sent if swap fails | | `excesses_address` | `address` | Address where TON excesses will be sent | | `additional_data` | `cell` | Cell with additional data | #### **`additional_data` body** | Name | Type | Description | | ------------------ | ----------- | -------------------------------------------------------------------------------------------------- | | `min_lp_out` | `coins` | Minimum required amount of lp tokens to receive | | `receiver_address` | `address` | Address where lp tokens will be sent | | `both_positive` | `uint1` | Trigger liquidity deposit only if both token amounts are non-zero | | `fwd_gas` | `coins` | Gas used to forward a message in `transfer_notification` after mint if `custom_payload` is present | | `custom_payload` | `maybe_ref` | Payload sent in `transfer_notification` after lp mint | #### **Outgoing messages** Sends a message to liquidity pool account with `add_liquidity` operation code. ### `reset_gas` (0x29d22935) Updates the amount of TON (in nanoTons) on the pool to `storage_fee::pool` (10000000) of the pool. The remaining amount of TON will be sent to `excesses_address`. #### **TL-B** ``` reset_gas#29d22935 query_id:uint64 = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ------------------ | --------- | ------------------------------------- | | `excesses_address` | `address` | Address where excess ton will be sent | #### **Outgoing messages** Sends a message to `excesses_address` with the remaining TON ### `internal_set_fees` (0x75930d63) Set new fee values including liquidity pool fees, protocol fees and referral fees as well as an address for receiving collected protocol fees. #### **TL-B** ``` internal_set_fees#75930d63 query_id:uint64 new_lp_fee:uint16 new_protocol_fee:uint16 new_protocol_fee_address:MsgAddress excesses_address:MsgAddress = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | -------------------------- | --------- | ------------------------------------------------------------------ | | `new_lp_fee` | `uint16` | New liquidity pool fee ratio (multiplied by `params::fee_divider`) | | `new_protocol_fee` | `uint16` | New protocol fee ratio (multiplied by `params::fee_divider`) | | `new_protocol_fee_address` | `address` | Address for receiving protocol fees | | `excesses_address` | `address` | Address where TON excesses will be sent | Notes: * fee ratio is the value of fee divided by `params::fee_divider` (10000); so to set a fee to 1% the value must be 100 * fees must be between `params::min_fee` (0) and `params::max_fee` (100) #### **Outgoing messages** Sends a message to `excesses_address` with the remaining TON *** ## Protocol address internal message handlers Handles messages from the `protocol_fee_address`. #### **Operations table** | Name | Value | Description | | -------------- | ---------- | ------------ | | `collect_fees` | 0x1ee4911e | Collect fees | ### `collect_fees` (0x1ee4911e) Collect protocol fees. The amount of fees in both tokens will be sent to `protocol_fee_address` address. #### **TL-B** ``` collect_fees#1ee4911e query_id:uint64 maybe_payload0:(Maybe ^Cell) maybe_payload1:(Maybe ^Cell) = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ----------- | ----------- | ----------------------------------------------- | | `payload_0` | `maybe_ref` | Payload used for `amount0`; can be `cross_swap` | | `payload_1` | `maybe_ref` | Payload used for `amount1`; can be `cross_swap` | #### **Outgoing messages** Sends a message with collected fees in both tokens to the router, which initiates `pay_to` operation to `protocol_fee_address`. ## LP Account internal message handlers Handles messages from an lp account. #### **Operations table** | Name | Value | Description | | ------------------ | ---------- | ------------------------------------------------- | | `cb_add_liquidity` | 0x06ecd527 | Sent by user's lp\_account after adding liquidity | | `cb_refund_me` | 0x0f98e2b8 | Sent by user's lp\_account after adding liquidity | ### `cb_add_liquidity` (0x06ecd527) Add new liquidity to the pool. Sent by user's lp account after both or one amounts 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#6ecd527 query_id:uint64 tot_am0:Coins tot_am1:Coins user_address:MsgAddress min_lp_out:Coins fwd_amount:Coins custom_payload_cs:(Maybe ^Cell) additional_fields:^[to_user_address:MsgAddress refund_address:MsgAddress excess_address:MsgAddress] = InternalMsgBody; ``` #### **Message body** | Name | Type | Description | | ----------------- | ----------- | ------------------------------------------------------------------------------------ | | `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 * 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 `to_address` with minted liquidity tokens ### `cb_refund_me` (0x0f98e2b8) 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#f98e2b8 query_id:uint64 tot_am0:Coins tot_am1:Coins user_address:MsgAddress left_maybe_payload:(Maybe ^Cell) right_maybe_payload:(Maybe ^Cell) = 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) | | `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` | #### **Outgoing messages** Sends a message with `amount0` of the first token and `amount1` of the second token to the router, which initiates `pay_to` operation *** ## Constants | Name | Value | Description | | ----------------------------------- | --------- | ------------------------------------------------------------------- | | `storage_fee::pool` | 10000000 | Amount of TON (in nanoTons) to be left on the pool contract as gas | | `params::required_min_liquidity` | 1001 | Minimum amount of liquidity required | | `MAX_COINS` | 2^120 - 1 | Maximum amount of tokens (in basic token units) stored as liquidity | | `gas::pool::provide_wallet_address` | 20000000 | Additional gas (in nanoTons) for providing a wallet | | `params::fee_divider` | 10000 | Fee values are divided by this value | | `params::min_fee` | 0 | Minimum fee allowed (0%) | | `params::max_fee` | 100 | Maximum fee allowed (1%) | --- # 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/v2/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.