Pool

Description

This contract implements V3 like functionality of the pool with concentrated liquidity.

Due to the new storage organization and availability of the dict data type we don't need the tickBitmap data structures. However, gas consumption while using the dict is also quite significant

Data Storage

Index	Type	Size (b/r)	Cell	Name	Description
1	addr	267 / 0	1	poolv3::router_address	Address of the router contract that created this pool (totally immutable set at creation )
2	uint16	16 / 0	1	poolv3::lp_fee_base	Liquidity provider fee. base in FEE_DENOMINATOR parts
3	uint16	16 / 0	1	poolv3::protocol_fee	Protocol fee in FEE_DENOMINATOR
4	uint16	16 / 0	1	poolv3::lp_fee_current	Current value of the pool fee, in case of dynamic adjustment
5	addr	267 / 0	1	poolv3::jetton0_wallet	Address of the 0 token in the pool. This is an address of the jetton0 wallet attached to router
6	addr	267 / 0	1	poolv3::jetton1_wallet	Address of the 1 token in the pool This is an address of the jetton0 wallet attached to router
7	int24	24 / 0	1	poolv3::tick_spacing	Spacing of the ticks, 24 bits of signed int would be used
8	uint64	64 / 0	1	poolv3::seqno	Used by indexer to ensure that none of pool interactions are skipped
9	uint256	256 / 0	11	poolv3::feeGrowthGlobal0X128	This variable stores current collected fee per the unit of liquidity in jetton0
10	uint256	256 / 0	11	poolv3::feeGrowthGlobal1X128	This variable stores current collected fee per the unit of liquidity in jetton0
11	uint128	128 / 0	11	poolv3::collectedProtocolFee0	Collected protocol fee of the jetton0
12	uint128	128 / 0	11	poolv3::collectedProtocolFee1	Collected protocol fee of the jetton1
13	coins	124 / 0	11	poolv3::reserve0	These are additional separate protection system - it calculates the reserves of the pool In case main math has a bug it protects the funds of other pools. Reserve of the jetton0
14	coins	124 / 0	11	poolv3::reserve1	Reserve of the jetton1
15	uint1	1 / 0	12	poolv3::pool_active	Pool acitve flag 0 is inactive, 1 is active
16	int24	24 / 0	12	poolv3::tick	Current tick, signed, 24 bits would be used. Pool maintains it in correspondence to poolv3::price_sqrt
17	uint160	160 / 0	12	poolv3::price_sqrt	Current square root of the price in Q64.96 format using 160 bits
18	uint128	128 / 0	12	poolv3::liquidity	Current active concentrated liquidity in 128 bits
19	uint24	24 / 0	12	poolv3::occupied_ticks	number of occupied ticks in storage
20	uint64	64 / 0	12	poolv3::nftv3item_counter	Pool is also an NFT collection. So this is the counter of currently minted positions
21	uint64	64 / 0	12	poolv3::nftv3items_active	Pool is also an NFT collection. Number of unburnt items
22	addr	267 / 0	12	poolv3::admin_address	Admin address. Can init pool
23	addr	267 / 0	12	poolv3::controller_address	Controller address. Can change fee and lock and unlock pool
24	addr	267 / 0	121	poolv3::jetton0_minter	Address of the 0 token minter. Beta only.
25	addr	267 / 0	121	poolv3::jetton1_minter	Address of the 1 token minter. Beta only.
26	dict	0 / 1	13	poolv3::ticks_dictionary	Storage of the ticks
27	code	0 / 1	14	poolv3::accountv3_code	Pool knows how to create user accounts to store fund pairs for a particular user
28	code	0 / 1	14	poolv3::position_nftv3_code	Pool knows how to create user position. So it stores it's code
29	cell	0 / 1	14	poolv3::nftv3_content	packed metadata that would be given to nft that corresponds to nft collection
30	cell	0 / 1	14	poolv3::nftv3item_content	packed metadata that would be given to nft that corresponds to the position

Cells

Name	Size	Free
1	937	86
11	1016	7
12	999	24
13	0	1023
14	0	1023
121	534	489

Interface

getIsActive

(int) getIsActive ()

Returns is pool is active

Return Values

#	Type	Description
0	int	int containing the poolv3::pool_active

getPoolStateAndConfiguration

(slice, slice, slice, slice, slice, slice, slice, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int ) getPoolStateAndConfiguration ()

Returns pool state and configuration

Return Values

#	Type	Description
0	slice	Router address
1	slice	Admin address
2	slice	Controller address
3	slice	Jetton 0 Wallet address. The wallet is owned by the Router
4	slice	Jetton 1 Wallet address. The wallet is owned by the Router
5	slice	Jetton 0 Minter address.
6	slice	Jetton 1 Minter address.
7	int	Flag that denotes if the pool is active
8	int	Pool tick spacing
9	int	Fee that is used as a base. Stored in x 1/10000
10	int	Fee that protocol takes. Stored in x 1/10000
11	int	Fee that is currently active. Stored in x 1/10000
12	int	Current tick
13	int	Current price
14	int	Current liquidity
15	int	poolv3::feeGrowthGlobal0X128
16	int	poolv3::feeGrowthGlobal1X128
17	int	Amount of jetton0 fee collected for protocol owners
18	int	Amount of jetton0 fee collected for protocol owners
19	int	Number of total minted NFT positions
20	int	Reserves of the jetton0
21	int	Reserves of the jetton1
22	int	Number of active NFT positions
23	int	Number of currently occupied ticks
24	int	Number of operations with pool since the deploy

getChildContracts

(cell, cell, cell, cell) getChildContracts ()

Return Values

#	Type	Description
0	cell	code of the account contract
1	cell	code of the nft position contract
2	cell	metadata for NFT Collection
3	cell	metadata for NFT Item

getAllTickInfos

(cell) getAllTickInfos ()

returns the cell with all the ticks.

Return Values

#	Type	Description
0	cell	cell that contains the dict with all the ticks.

getTickInfosFrom

(tuple) getTickInfosFrom (int key, int amount, int dir, int full)

Returns ticks starting form key (non-inclusive)

0 forward
1 backward

Parameters

#	Type	Name	Description
0	int	key	key (tick number) from which to get data
1	int	amount	amount of ticks to get (large values would fail with out of gas)
2	int	dir	0 - for forward search, 1 - for backward
3	int	full	with true (non zero) would fill fee counter values

getCollectedFees

(int, int) getCollectedFees (int tickLower, int tickUpper, int posLiquidityDelta, int posFeeGrowthInside0X128, int posFeeGrowthInside1X128)

Predicts how much fees a position can collect

Parameters

#	Type	Name
0	int	tickLower
1	int	tickUpper
2	int	posLiquidityDelta
3	int	posFeeGrowthInside0X128
4	int	posFeeGrowthInside1X128

Return Values

#	Type	Description
0	int	amount of jetton0 that is collected
1	int	amount of jetton1 that is collected

getUserAccountAddress

(slice) getUserAccountAddress (slice user_address)

computes user account address for a given user

Parameters

#	Type	Name	Description
0	slice	user_address	address for witch account address is requested

Return Values

#	Type	Description
0	slice	account address

getMintEstimate

(int, int, int) getMintEstimate (int tickLower, int tickUpper, int liquidity)

Computes estimates for the mint

Parameters

#	Type	Name	Description
0	int	tickLower	lower tick for the desired position
1	int	tickUpper	upper tick for the desired position
2	int	liquidity	liquidity that is planned to be minted

Return Values

#	Type	Description
0	int	amount of jetton0 needed to mint the position
1	int	amount of jetton1 needed to mint the position
2	int	error code that shows if the basic checks for the mint would succeed

getSwapEstimate

(int, int) getSwapEstimate (int zeroForOne, int amount, int sqrtPriceLimitX96)

Deprecated. Use getSwapEstimateGas instead

Computes estimates fot the swap

Parameters

#	Type	Name	Description
0	int	zeroForOne	direction of the swap zeroForOne !=0 - swap jetton0 for jetton1, otherwise jetton1 for jetton0
1	int	amount	amount of input token for the swap
2	int	sqrtPriceLimitX96	limit price (formatted as fixed point 64.96 square root of the price).If reached - swap will stop

Return Values

#	Type	Description
0	int	amount of jetton0 that would be put to/get from the pool
1	int	amount of jetton1 that would be put to/get from the pool

getSwapEstimateGas

(int, int) getSwapEstimateGas (int zeroForOne, int amount, int sqrtPriceLimitX96, int minOutAmount, int gasLimit)

Computes estimates for the swap

Parameters

#	Type	Name	Description
0	int	zeroForOne	direction of the swap zeroForOne !=0 - swap jetton0 for jetton1, otherwise jetton1 for jetton0
1	int	amount	amount of input token for the swap
2	int	sqrtPriceLimitX96	limit price (formatted as fixed point 64.96 square root of the price).If reached - swap will stop (swap would succeed remaining input amount would return as change )
3	int	minOutAmount	minimum amount. If return value would be less than this, swap will be reverted
4	int	gasLimit	amount of gas (in gas units). If gasLimit is 0 - default value is used - that equals to contract gas limit from the config

Return Values

#	Type	Description
0	int	amount of jetton0 that would be put to/get from the pool
1	int	amount of jetton1 that would be put to/get from the pool

get_collection_data

(int, cell, slice) get_collection_data ()

In accordance with TEP-62

Return Values

#	Type	Description
0	int	poolv3::nftv3item_counter
1	cell	poolv3::nftv3_content
2	slice	poolv3::router_address

get_nft_address_by_index

(slice) get_nft_address_by_index (int index)

In accordance with TEP-62

Parameters

#	Type	Name	Description
0	int	index	index of the requested NFT (Position NFT)

Return Values

#	Type	Description
0	slice	address of the Position NFT

get_nft_content

(cell) get_nft_content (int index, cell nftv3item_content)

In accordance with TEP-62 we will form the output NFT onchain metadata

If NFTItemContent "description" field that is passed to the pool by the pool administrator (poolv3::nftv3item_content) begins with marker "%N%", data from the NFT is added to the beginning of the "description" field. If there is no data attached to the dictionary by the NFT, NFTItemContent description is unchanged

Parameters

#	Type	Name	Description
0	int	index	index of the requested NFT
1	cell	nftv3item_content	NFT content returned from the get_nft_data() of the NFT

Return Values

#	Type	Description
0	cell	cell with metadata dict()

Messages

POOLV3_INIT

Opcode : 0x441c39ed

The first mandatory operation that fills crucial parameters of the pool
\

Path	Mnemonic	Type	Description
	op	Uint(32),op
	query_id	Uint(64)	queryid as of the TON documentation
	from_admin	Uint(1),Bool	Flag that shows if this message goes from router admin or pool factory
	has_admin	Uint(1),Bool	Flag that shows if this message have a new admin address
	admin_addr	Address(267)	New address of the admin. If has_admin is false could be 00b
	has_controller	Uint(1),Bool	Flag that shows if this message have a new controller address
	controller_addr	Address(267)	Address that is allowed to change the fee. Can always be updated by admin. If has_controller is false could be 00b
	set_spacing	Uint(1),Bool	Flag that shows if tick_spacing should be set to the pool or ignored
	tick_spacing	Int(24)	Tick spacing to be used in the pool
	set_price	Uint(1),Bool	Flag that shows if initial_priceX96 should be set to the pool or ignored
	initial_priceX96	Uint(160),PriceX96	Initial price for the pool
	set_active	Uint(1),Bool	Flag that shows if pool_active should be set to the pool or ignored
	pool_active	Uint(1),Bool	Flag is we should start the pool as unlocked
	protocol_fee	Uint(16),Fee	Liquidity provider fee. base in FEE_DENOMINATOR parts. If value is more than 10000 value would be default
	lp_fee_base	Uint(16),Fee	Protocol fee in FEE_DENOMINATOR. If value is more than 10000 value would be default
	lp_fee_current	Uint(16),Fee	Current value of the pool fee, in case of dynamic adjustment. If value is more than 10000 value would be default
	nftv3_content	Cell(0),Metadata	Metadata for the NFT Collection
	nftv3item_content	Cell(0),Metadata	Metadata for the NFT Item
	0	Maybe Cell(1) minter_cell	Cell With Minters
0	jetton0_minter	Address(267)	Address of the jetton0 minter, used by indexer and frontend
0	jetton1_minter	Address(267)	Address of the jetton1 minter, used by indexer and frontend

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_INIT

POOLV3_INIT#441c39ed 
    query_id:uint64
    from_admin:uint1
    has_admin:uint1
    admin_addr:MsgAddress
    has_controller:uint1
    controller_addr:MsgAddress
    set_spacing:uint1
    tick_spacing:int24
    set_price:uint1
    initial_priceX96:uint160
    set_active:uint1
    pool_active:uint1
    protocol_fee:uint16
    lp_fee_base:uint16
    lp_fee_current:uint16
    nftv3_content:Cell
    nftv3item_content:Cell
    minter_cell:(Maybe ^[
        jetton0_minter:MsgAddress
        jetton1_minter:MsgAddress
    ] ) 
= ContractMessages;

POOLV3_LOCK

Opcode : 0x5e74697

This operation locks the pool. This is allowed to do by the operator and the admin
\

Path	Mnemonic	Type	Description
	op	Uint(32),op
	query_id	Uint(64)	queryid as of the TON documentation

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_LOCK

POOLV3_LOCK#5e74697 
    query_id:uint64
= ContractMessages;

POOLV3_UNLOCK

Opcode : 0x3205adbd

This operation locks the pool. This is allowed to do by the operator and the admin
\

Path	Mnemonic	Type	Description
	op	Uint(32),op
	query_id	Uint(64)	queryid as of the TON documentation

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_UNLOCK

POOLV3_UNLOCK#3205adbd 
    query_id:uint64
= ContractMessages;

POOLV3_MINT

Opcode : 0x81702ef8

Mnemonic	Type	Description
op	Uint(32),op
query_id	Uint(64)	queryid as of the TON documentation
amount0Funded	Coins(124)	Amount of jetton 0 received by router for the mint
amount1Funded	Coins(124)	Amount of jetton 1 recived by router for the mint
recipient	Address(267)	Address that would receive the minted NFT, excesses and refunds
liquidity	Uint(128)	Amount of liquidity to mint
tickLower	Int(24)	lower bound of the range in which to mint
tickUpper	Int(24)	upper bound of the range in which to mint

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_MINT

POOLV3_MINT#81702ef8 
    query_id:uint64
    amount0Funded:(VarUInteger 16)
    amount1Funded:(VarUInteger 16)
    recipient:MsgAddress
    liquidity:uint128
    tickLower:int24
    tickUpper:int24
= ContractMessages;

POOLV3_BURN

Opcode : 0xd73ac09d

Burn whole or part of nft. Is sent by Position NFT itself, would only be accepted from the correct NFT itself
\

Path	Mnemonic	Type	Description
	op	Uint(32),op
	query_id	Uint(64)	queryid as of the TON documentation
	recipient	Address(267)	NFT owner to receive funds
	burned_index	Uint(64)	Index if the NFT to burn. Should match the sender address
	liquidity	Uint(128)	NFT liquidity amount prior to burn
	tickLower	Int(24)	Lower tick of the NFT. Sanitized by NFTPosition contract
	tickUpper	Int(24)	Upper tick of the NFT. Sanitized by NFTPosition contract
	liquidity2Burn	Uint(128)	Amount of the liquidity to burn, 0 is a valid amount, in this case only collected fees would be returned
	0	Cell(0) old_fee_cell	Fee counters to collect from
0	feeGrowthInside0LastX128	Uint(256),x128	Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
0	feeGrowthInside1LastX128	Uint(256),x128	Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point
	1	Cell(0) new_fee_cell	Fee counters to collect to (Used by indexer)
1	feeGrowthInside0CurrentX128	Uint(256),x128,Indexer	Fee counter inside position range for jetton0, per unit of liquidity, in 128.128 fixed point
1	feeGrowthInside1CurrentX128	Uint(256),x128,Indexer	Fee counter inside position range for jetton1, per unit of liquidity, in 128.128 fixed point

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_BURN

POOLV3_BURN#d73ac09d 
    query_id:uint64
    recipient:MsgAddress
    burned_index:uint64
    liquidity:uint128
    tickLower:int24
    tickUpper:int24
    liquidity2Burn:uint128
    old_fee_cell:^[
        feeGrowthInside0LastX128:uint256
        feeGrowthInside1LastX128:uint256
    ]  
    new_fee_cell:^[
        feeGrowthInside0CurrentX128:uint256
        feeGrowthInside1CurrentX128:uint256
    ]  
= ContractMessages;

POOLV3_SET_FEE

Opcode : 0x6bdcbeb8

This operation sets the fee values for the pool. This is allowed to do by the operator and the admin
\

Mnemonic	Type	Description
op	Uint(32),op
query_id	Uint(64)	queryid as of the TON documentation
protocol_fee	Uint(16)	Liquidity provider fee. base in FEE_DENOMINATOR parts
lp_fee_base	Uint(16)	Protocol fee in FEE_DENOMINATOR
lp_fee_current	Uint(16)	Current value of the pool fee, in case of dynamic adjustment

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_SET_FEE

POOLV3_SET_FEE#6bdcbeb8 
    query_id:uint64
    protocol_fee:uint16
    lp_fee_base:uint16
    lp_fee_current:uint16
= ContractMessages;

POOLV3_FUND_ACCOUNT

Opcode : 0x4468de77

Proxy proof of the jettons funding and mint request to the AccountV3. For more information refer to AccountV3
\

Mnemonic	Type	Description
op	Uint(32),op
query_id	Uint(64)	queryid as of the TON documentation
owner_addr	Address(267)	Address that would receive the minted NFT, excesses and refunds
amount0	Coins(124)	Amount of jetton0 that is funded for the mint
amount1	Coins(124)	Amount of jetton1 that is funded for the mint
enough0	Coins(124)	Minimum amount of jetton0 totally collected on the account that is required to start the mint
enough1	Coins(124)	Minimum amount of jetton1 totally collected on the account that is required to start the mint
liquidity	Uint(128)	Amount of liquidity to mint
tickLower	Int(24)	lower bound of the range in which to mint
tickUpper	Int(24)	upper bound of the range in which to mint

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_FUND_ACCOUNT

POOLV3_FUND_ACCOUNT#4468de77 
    query_id:uint64
    owner_addr:MsgAddress
    amount0:(VarUInteger 16)
    amount1:(VarUInteger 16)
    enough0:(VarUInteger 16)
    enough1:(VarUInteger 16)
    liquidity:uint128
    tickLower:int24
    tickUpper:int24
= ContractMessages;

POOLV3_START_BURN

Opcode : 0x530b5f2c

Burn whole or part of nft. Can be called by anyone, but if not called be the owner - would fail later. This operation would compute the amount of the fees that the position is eligible to get and then forwards a message to the Position NFT contract
\

Mnemonic	Type	Description
op	Uint(32),op
query_id	Uint(64)	queryid as of the TON documentation
burned_index	Uint(64)	Index if the NFT to burn
liquidity2Burn	Uint(128)	Amount of the liquidity to burn, 0 is a valid amount, in this case only collected fees would be returned
tickLower	Int(24)	Lower tick of the NFT. Should match the real one
tickUpper	Int(24)	Upper tick of the NFT. Should match the real one

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_START_BURN

POOLV3_START_BURN#530b5f2c 
    query_id:uint64
    burned_index:uint64
    liquidity2Burn:uint128
    tickLower:int24
    tickUpper:int24
= ContractMessages;

POOLV3_SWAP

Opcode : 0xa7fb58f8

Computes the swap math, and issues a command to the router to send funds. Only would be accepted from the router This operation we have several input parameters that would affect the result of the swap

Condition	Swap result	Returned Change	Error Code
Swap finished sqrtPriceLimitX96 not reached. minOutAmount surpassed	total output number of coins	0	RESULT_SWAP_OK
Swap finished minOutAmount not surpassed	0	amount	RESULT_SWAP_OUTPUT_TOO_SMALL
Swap reached sqrtPriceLimitX96 after changing part1 coins. minOutAmount surpassed	output number of coins	amount - part1	RESULT_SWAP_OK

Access Rights: This operation is allowed for poolv3::router_address\

Path	Mnemonic	Type	Description
	op	Uint(32),op
	query_id	Uint(64)	queryid as of the TON documentation
	owner_address	Address(267)	Owner of the liquidity in swap
	source_wallet	Address(267)	jetton wallet attached to the router. used to identify swap direction
	0	Cell(0) params_cell	Fee counters To (Used by indexer)
0	amount	Coins(124)	Input amount of the jettons to be swapped
0	sqrtPriceLimitX96	Uint(160),PriceX96	Limit marginal price. Swap won't go beyond it.
0	minOutAmount	Coins(124)	Minimum amount of the output jettons to get back. If not reached, your input would be returned to you
	1	Cell(0) payloads_cell	Cell with payloads for swap result and change
1	target_address	Address(267)	Target will receive the result of the swap. Could be addr_none() (00b) then owner_address is used
1	ok_forward_amount	Coins(124)	Amount of GRAM to use for forward payload that would be sent with the result of the swap
1	ok_forward_payload	Cell(0),Maybe,Payload	Payload that would be sent with the jettons of the result of the swap
1	ret_forward_amount	Coins(124)	Amount of GRAM to use for forward payload that would be sent with the change for the swap (if any)
1	ret_forward_payload	Cell(0),Maybe,Payload	Payload that would be sent with the jettons of the change of the swap (if any)

TL-B Description (TBD)

This is a preliminary tl-b - subject to change

Tlb for POOLV3_SWAP

POOLV3_SWAP#a7fb58f8 
    query_id:uint64
    owner_address:MsgAddress
    source_wallet:MsgAddress
    params_cell:^[
        amount:(VarUInteger 16)
        sqrtPriceLimitX96:uint160
        minOutAmount:(VarUInteger 16)
    ]  
    payloads_cell:^[
        target_address:MsgAddress
        ok_forward_amount:(VarUInteger 16)
        ok_forward_payload:(Maybe ^Cell)
        ret_forward_amount:(VarUInteger 16)
        ret_forward_payload:(Maybe ^Cell)
    ]  
= ContractMessages;

Keyboard shortcuts

TONCO Docs