TL-B Schemes
This page contains extensive information about custom entities used in communication with/in-between swap.coffee DEX contracts.
Types
AMM
Defines AMM strategy type of the pool.
AMM Settings
Some AMM strategies require additional settings whenever pool with such strategy is about to be created. Person who initiates this process must provide AMM settings cell within the transaction. Please, keep in mind that non-Constant Product pools may be created by the DEX administration only.
CurveFi Stable
Property Name | Meaning |
---|---|
amplification | Multiplier used in StableSwap formulas. The higher this value is, the closer exchange price stays to 1:1. The lower this value is, the more exchange price looks like from Constant Product formula |
asset1_weight | Value by which first asset reserves and amounts multiplied in StableSwap formulas. Usually a power of 10 |
asset2_weight | Value by which second asset reserves and amounts multiplied in StableSwap formulas. Usually a power of 10 |
DepositLiquidityCondition
Defines condition, which will be checked whenever contract receives liquidity deposition request. If it fails, transaction will be reverted.
none
Equivalent to no-condition.
lp_quantity
Allows to set minimum quantity of LP tokens you will get in return after liquidity deposition happens. If real quantity is lower than the given one, transaction will be reverted.
reserves_ratio
Allows to check pool reserves ratio before your liquidity deposition happens. In other words, all of the following formulas must be true:
reserves1 / reserves2 >= min_nominator / denominator
reserves1 / reserves2 <= max_nominator / denominator
complex
Just a combination of none and reserves_ratio.
Asset
Defines asset type (and metadata) to work with.
native
Used for TONcoin.
jetton
Used for any jettons.
extra
Used for extra currencies.
PoolParams
Used to uniquely identify the pool. Only one pool can exist for given asset-pair and AMM type.
NotificationDataSingle
Defines where to send (and with how much gas) custom payload for various actions within DEX.
If receiver
is none, it’s considered being equal to transaction recipient.
NotificationData
Defines how to handle notifications (custom payloads) in none of, one of or both scenarios of successful/failed execution.
PoolUpdateParams
Defines pool’s parameters that may be updated by DEX administrator.
SwapParams
Defines parameters that are essential for all (multi-hop) steps of single swap transaction:
Property Name | Meaning |
---|---|
deadline | Unix timestamp. If contract receives swap message after that time, transaction will be failed at that step |
recipient | Address to which funds must go after swap transaction is over (both in success/failure scenarios). Must be present |
referral | Address to which referral fees will be accrued. If none, referral fees go to the protocol |
notification_data | Used for custom payloads. See: NotificationData |
SwapStepParams
Defines parameters that are unique for every (multi-hop) step of swap transaction:
Property Name | Meaning |
---|---|
pool_address_hash | Hash part of the pool’s address |
min_output_amount | Minimum quantity of output asset to receive. If you get less, transaction will fail |
next | Next swap-step if any |
SwapStepInternalParams
Same as SwapStepParams, but is being used in inter-contract communication.
Property Name | Meaning |
---|---|
previous_amount | Amount of asset you received on the previous swap-step |
previous_asset_hint | Asset you received on the previous swap-step. It’s present only in cases when user tries to perform sequential swaps on pools of the same asset-pairs (but probably different AMM types) |
min_output_amount | Minimum quantity of output asset to receive. If you get less, transaction will fail |
next | Next swap-step if any |
PoolReserves
Defines reserves of the pool.
DepositLiquidityParamsTrimmed
Defines parameters required for liquidity provisioning. This exact entity is being used in inter-contract communication and lacks some of extra information (see below).
Property Name | Meaning |
---|---|
recipient | Address to which LP tokens must go after transaction succeed (or to which funds must return in failure scenario). Must be present |
referral | Referral address used exclusively for analytical purposes. No fees or any kind or rewards will be given |
deadline | Unix timestamp. If contract receives liquidity provisioning message after that time, transaction will be failed at that step |
condition | Used to protect the liquidity provider from unfavorable pool conditions. See: DepositLiquidityCondition |
notification_data | Used for custom payloads. See: NotificationData |
DepositLiquidityParams
Extended version of the previous one. Pool parameters are used to identify the pool.
ContractUpdate
Entity used in administrative action of contract updates.
Messages
Related to swaps
SwapNative
Must be sent by user to the Native Vault to initiate swap transaction.
Property Name | Meaning |
---|---|
query_id | Non-unique identifier which you may specify to track this transaction |
amount | Amount of TONs to swap. Must be lower than the message value of TONs (because extra TONs will be used to pay for gas, and will be returned at the end of the transaction) |
_ | Parameters for the first swap-step of the transaction. See: SwapStepParams |
params | Parameters that are essential for all steps of the swap transaction. See: SwapParams |
SwapJetton
Must be sent by user to the corresponding Jetton Vault as a custom payload of a jetton-transfer message to initiate swap transaction.
Query ID, jetton and it’s amount are being determined internally from jetton transfer notification and therefore mustn’t be present here.
Property Name | Meaning |
---|---|
_ | Parameters for the first swap-step of the transaction. See: SwapStepParams |
params | Parameters that are essential for all steps of the swap transaction. See: SwapParams |
SwapExtra
Must be sent by user to the corresponding Extra-Currency Vault to initiate swap transaction.
Extra-currency and it’s amount are being determined internally from the vault type and extra-currencies dictionary within the message.
Property Name | Meaning |
---|---|
query_id | Non-unique identifier which you may specify to track this transaction |
_ | Parameters for the first swap-step of the transaction. See: SwapStepParams |
params | Parameters that are essential for all steps of the swap transaction. See: SwapParams |
SwapSuccessfulEvent
Is being sent by the pool as an external outgoing message whenever swap step completes successfully.
This message occurs after payout is guaranteed to happen, but before it actually happens.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
input | Input (given) asset of the swap operation. There is no output asset property, but it may be determined from the pool address and data |
input_amount | Amount of input (given) asset of the swap operation |
output_amount | Amount of output (received) asset of the swap operation |
reserves | Pool’s reserves at the moment swap happened |
SwapFailedEvent
Is being sent by the pool as an external outgoing message whenever swap step completes badly (i.e. it was slippage tolerated or deadline exceeded).
This message occurs after payout (of the input asset) is guaranteed to happen, but before it actually happens.
Despite the fact that message itself does not contain failure reason, it may be determined as an exit code of the TVM.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
input | Input (given) asset of the swap operation. There is no output asset property, but it may be determined from the pool address and data |
input_amount | Amount of input (given) asset of the swap operation |
reserves | Information about pool’s reserves at a time it tries to execute this transaction. Guaranteed to be present to slippage-tolerated failures only |
Related to pools creation and liquidity provisioning
CreatePoolNative
Must be sent by user to the Native Vault as a part of pool creation (and it’s initial liquidity provisioning).
Property Name | Meaning |
---|---|
query_id | Non-unique identifier which you may specify to track this transaction |
amount | Amount of TONs to deposit into liquidity. Must be lower than the message value of TONs (because extra TONs will be used to pay for gas, and will be returned at the end of the transaction) |
params | Parameters used to uniquely identify the pool. See: PoolParams |
amm_settings | Cell of AMM settings. Must be set for those AMMs that require it |
notification_data | Used for custom payloads. See: NotificationData |
CreatePoolJetton
Must be sent by user to the corresponding Jetton Vault as a part of pool creation (and it’s initial liquidity provisioning). This message must be included as a custom payload to the jetton-transfer message.
Query ID, jetton and it’s amount are being determined internally from jetton transfer notification and therefore mustn’t be present here.
Property Name | Meaning |
---|---|
params | Parameters used to uniquely identify the pool. See: PoolParams |
amm_settings | Cell of AMM settings. Must be set for those AMMs that require it |
notification_data | Used for custom payloads. See: NotificationData |
CreatePoolExtra
Must be sent by user to the corresponding Extra-Currency Vault as a part of pool creation (and it’s initial liquidity provisioning).
Extra-currency and it’s amount are being determined internally from the vault type and extra-currencies dictionary within the message.
Property Name | Meaning |
---|---|
query_id | Non-unique identifier which you may specify to track this transaction |
params | Parameters used to uniquely identify the pool. See: PoolParams |
amm_settings | Cell of AMM settings. Must be set for those AMMs that require it |
notification_data | Used for custom payloads. See: NotificationData |
DepositLiquidityNative
Must be sent by user to the Native Vault as a part of liquidity provisioning process.
Property Name | Meaning |
---|---|
query_id | Non-unique identifier which you may specify to track this transaction |
amount | Amount of TONs to deposit into liquidity. Must be lower than the message value of TONs (because extra TONs will be used to pay for gas, and will be returned at the end of the transaction) |
params | Parameters used for liquidity provisioning. See: DepositLiquidityParams |
DepositLiquidityJetton
Must be sent by user to the corresponding Jetton Vault as a part of liquidity provisioning process. This message must be included as a custom payload to the jetton-transfer message.
Query ID, jetton and it’s amount are being determined internally from jetton transfer notification and therefore mustn’t be present here.
Property Name | Meaning |
---|---|
params | Parameters used for liquidity provisioning. See: DepositLiquidityParams |
DepositLiquidityExtra
Must be sent by user to the corresponding Extra-Currency Vault as a part of liquidity provisioning process.
Extra-currency and it’s amount are being determined internally from the vault type and extra-currencies dictionary within the message.
Property Name | Meaning |
---|---|
query_id | Non-unique identifier which you may specify to track this transaction |
params | Parameters used for liquidity provisioning. See: DepositLiquidityParams |
DepositLiquiditySuccessfulEvent
Is being sent by the pool as an external outgoing message whenever liquidity provisioning step completes successfully.
This message occurs after LP tokens payout is guaranteed to happen, but before it actually happens.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
amount1 | Amount of pool’s first asset that were used for the liquidity provisioning |
amount2 | Amount of pool’s second asset that were used for the liquidity provisioning |
lp_amount | Amount of LP tokens user received as a result of this liquidity provisioning |
total_supply | Information about how pool’s LP tokens total supply changed with this operation |
reserves | Pool’s reserves at the moment this operation happened |
DepositLiquidityFailedEvent
Is being sent by the pool as an external outgoing message whenever liquidity provisioning step completes badly (i.e. it’s condition check failed or deadline exceeded).
This message occurs after payout (of provided assets) is guaranteed to happen, but before it actually happens.
Despite the fact that message itself does not contain failure reason, it may be determined as an exit code of the TVM.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
amount1 | Amount of pool’s first asset that were about to be used for the liquidity provisioning |
amount2 | Amount of pool’s second asset that were about to be used for the liquidity provisioning |
min_lp_amount | Minimum amount of LP tokens user was asking for |
total_supply | Total supply of LP tokens at the moment this liquidity provisioning was about to happen |
reserves | Pool’s reserves at the moment this liquidity provisioning was about to happen |
LiquidityWithdrawalEvent
Is being sent by the pool as an external outgoing message whenever somebody withdraws previously provided liquidity.
This message occurs after payout is guaranteed to happen, but before it actually happens.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
amount1 | Amount of pool’s first asset that will be sent to the user |
amount2 | Amount of pool’s second asset that will be sent to the user |
lp_amount | Amount of LP tokens being burnt |
total_supply | Information about how pool’s LP tokens total supply changed with this operation |
reserves | Pool’s reserves at the moment this operation happened |
WithdrawDeposit
Must be sent by the user to the PoolCreator or LiquidityDepository if only one of 2 liquidity provisioning transactions succeeded and user decides to cancel previously initiated process. As a result of this message execution, all half-way deposited funds will be returned back to the user.
Miscellaneous
Payout
Is being sent by the Native Vault and Extra-Currency Vaults in some cases. More specifically, it occurs if:
- Operation was initiated without notifications (custom payloads)
- Operation was initiated with notification, but it’s recipient differs from the wallet that receives funds
It means that in a situation when operation was initiated with notification, but it’s recipient is the same as the one who receives funds, this message won’t be created.
CreateVault
Must be sent by a user to the Factory in order to create new vault.
Property Name | Meaning |
---|---|
query_id | Non-unique identifier which you may specify to track this transaction |
asset | Asset for which new vault must be created |
Inter-contract communication
SwapInternal
For any first step of swap transaction, this message will be sent from Vaults to the Pool. For any intermediate steps of swap transaction, it will be sent from one Pool to another.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
_ | Parameters of the current swap step |
params | Parameters which are essential for all steps of this swap transaction |
proof | Special cell constructed for securing inter-contract communication |
PayoutInternal
Is being sent by Pools to the Vaults every time Pool decides that a payment must happen.
Keep in mind that there’s no asset defined in the message, because it can be determined by the Vault data.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
recipient | Address of the one who will receive funds |
amount | Amount of asset to be sent to the recipient |
notification_data | Used for custom payloads. See: NotificationData |
proof | Special cell constructed for securing inter-contract communication |
Deploy
Is being sent by Factory every time it decides to deploy a new contract.
Property Name | Meaning |
---|---|
code | Code of the contract |
data | Data of the contract |
action | Optional code cell that must be invoked after contract initialization |
CreatePoolCreatorRequest
Is being sent by Vaults to the Factory at the moment somebody tries to create new pool.
Keep in mind that there’s no asset defined in the message, because it can be determined by the Vault data.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
amount | Amount of this vault’s asset user provided as an initial liquidity for the pool |
params | Parameters to uniquely identify the pool to be created |
amm_settings | Cell of AMM settings. Must be set for those AMMs that require it |
recipient | Address of the one who will receive LP tokens |
notification_data | Used for custom payloads. See: NotificationData |
proof | Special cell constructed for securing inter-contract communication |
CreatePoolCreatorInternal
Is being sent by the Factory whenever it’s about to deploy new PoolCreator.
Properties are pretty much the same with CreatePoolCreatorRequest.
CreatePoolRequest
Is being sent by the PoolCreator to the Factory when it’s time the uninitialize PoolCreator and deploy a Pool.
Properties are pretty much the same with CreatePoolCreatorRequest.
CreatePoolInternal
Is being sent by the Factory whenever it’s about to deploy new Pool.
Properties are pretty much the same with CreatePoolCreatorRequest.
CreateLiquidityDepositoryRequest
Is being sent by Vaults to the Factory at the moment somebody tries to deposit liquidity to some pool.
Keep in mind that there’s no asset defined in the message, because it can be determined by the Vault data.
Property Name | Meaning |
---|---|
query_id | Propagated identifier |
amount | Amount of this vault’s asset user provided as a liquidity for the pool |
params | Parameters for liquidity provisioning. See DepositLiquidityParams |
proof | Special cell constructed for securing inter-contract communication |
CreateLiquidityDepositoryInternal
Is being sent by the Factory whenever it’s about to deploy new LiquidityDepository.
Properties are pretty much the same with CreateLiquidityDepositoryRequest.
DepositLiquidityInternal
Is being sent by the LiquidityDepository to the Pool when it’s time to uninitialize LiquidityDepository and execute liquidity provisioning on the Pool side.
Properties are pretty much the same with CreateLiquidityDepositoryRequest.
CreateVaultInternal
Is being sent by the Factory whenever it’s about to deploy new Vault.
UpdatePoolInternal
Is being sent by the Factory to the Pool whenever it receives administrative request to do so.
ActivateVaultInternal
Is being sent by the Factory to the Vault whenever it receives administrative request to do so.
When Factory creates new Jetton Vault, it internally initiates process of determining it’s own jetton wallet’s address. It is required to ensure security later on, but unfortunately in order to obtain that address Jetton Vault needs to ask Jetton Master for it. Not all Jetton Masters support such thing on-chain, therefore for some older jettons administrative affection is required.
UpdateContractInternal
Is being sent by the Factory to any DEX contract whenever it receives administrative request to do so.
Administrative
UpdateAdmin
Must be sent from the administrative wallet to the Factory in order to update administrative wallet’s address.
UpdatePool
Must be sent from the administrative wallet to the Factory in order to update parameters of the pool.
ActivateVault
Must be sent from the administrative wallet to the Factory in order to activate some Jetton Vault.
Withdraw
Must be sent from the withdrawer wallet to the Factory in order to withdraw some assets.
Used to withdraw protocol and referral fees: they are not distributed (nor calculated) on-chain, because it will lead to significantly higher gas consumption for end-users.
UpdateCodeCell
Must be sent from the administrative wallet to the Factory in order to update code cells of all the contracts that will be deployed by the Factory in the future.
UpdateContract
Must be sent from the administrative wallet to the Factory in order to update already existing contract.
contract_address
must be none in case of administrator wanting to upgrade the Factory itself.
UpdateWithdrawer
Must be sent from the administrative wallet to the Factory in order to update withdrawer wallet’s address.