Generic Information
All code examples are written in TypeScript using Blueprint. If you need more implementation details, refer to the DEX source code: it contains OOP implementations of all contracts, so this page is likely temporary until a full-fledged SDK is created based on that code. This document is for reference only and may contain errors. If you come across any, please consider contacting us via Telegram @swap.coffee DEV Chat.(De)serialization of assets
Vaults
Checking for existence and activity
To check whether asset’s Vault exists and is active, you firstly need to fetch its address from the factory, then invoke a get-method is_active.Creating a new one
To create a new Vault, you need to send a create_vault internal message to the factory. If you are creating a Vault for jetton, make sure it goes through activation process as described here. If it was unable to automatically activate itself, please contact us via Telegram @swap.coffee DEV Chat.Pools
Creating a new one
- Check that Vaults for both assets exist and are active (or create them instead).
- Send create_pool messages to both Vaults. Type of each message depends on the type of asset of associated Vault:
- For TON, use create_pool_native.
- For Jetton, use create_pool_jetton as a forward payload in jetton_transfer.
- For Extra Currency, use create_pool_extra.
Providing liquidity to existing one
All you need is to send deposit_liquidity messages to both Vaults. Type of each message depends on the type of asset of associated Vault:- For TON, use deposit_liquidity_native.
- For Jetton, use deposit_liquidity_jetton as a forward payload in jetton_transfer.
- For Extra Currency, use deposit_liquidity_extra.
Rolling back liquidity provisioning
Both pool creation and liquidity provisioning operations require 2 transactions with corresponding assets to be sent. If only one of them appeared in the blockchain, you may want to rollback the whole process, therefore receiving sent funds back. In order to do so, please follow the given instructions:- Inspect the one transaction that appeared in the blockchain, and find out
pool_creator
orliquidity_depository
contract address. It is the last contract in the transaction execution chain. - Send a withdraw_deposit message to that contract.
Performing a swap
- Fetch Vault’s address from factory for the input asset.
- Fetch Pools addresses from factory (or another source of truth) for every pool throughout your way.
- Send swap message to the Vault of input asset. Type of the message depends on the type of asset:
- For TON, use swap_native.
- For Jetton, use swap_jetton as a forward payload in jetton_transfer.
- For Extra Currency, use swap_extra.
Notifications
Notifications are a system that allows sending acustom_payload
upon the successful or failed execution of
operations on the DEX.
They can be used during pool creation, liquidity provisioning or withdrawal, as well as performing swaps. In all these
cases, the approach to using notifications is the same: they are optional, and you can specify a notification for only
the success case, only the failure case, or define separate notifications for each outcome. Each notification can carry
a unique custom_payload
and have a distinct recipient.
Notifications are passed as an additional parameter when constructing a transaction to be sent by the user. However,
depending on the operation, there are some differences in how they are ultimately processed. More on that below.
Keep in mind that depending on the situation, a notification may be sent either as an internal message with its own
opcode, or as a forward_payload
within a jetton_transfer
. In both cases, the user-defined custom_payload
is not
sent directly: instead, it is encapsulated within a separate entity.
In other words, the recipient must either be capable of handling notification’s opcode, or a proxy contract must be used
to unwrap the encapsulated message and forward it further.
The fwd_gas
for notification must be explicitly specified in cases where the notification recipient differs from the
funds recipient, or when the notification is sent as a forward_payload
within a jetton_transfer
.
On pool creation or liquidity provisioning
- In case of failure, the notification will be sent twice - once from each Vault, along with the refund of the assets that were intended for liquidity provision.
- In case of success, the notification will be sent once, but the delivery method may vary:
- If the notification recipient is the same as the LP tokens recipient, the notification will be delivered as a
forward_payload
inside thejetton_transfer
that sends the LP tokens. - If recipients differ, the notification will be sent as an internal message with its own opcode.
- If the notification recipient is the same as the LP tokens recipient, the notification will be delivered as a
On liquidity withdrawal
For liquidity withdrawals only on-success notification may be provided. If operation succeeds, the notification will be sent twice - once from each Vault, along with the refund of the assets that were received as a result of a liquidity withdrawal.On swap
In all cases the notification will be sent once throughout the Vault. The method of delivery may vary:- If the recipient of the funds is different from the notification recipient, the notification will be sent as an internal message with its own opcode.
- If both the funds and the notification are to be sent to the same address, the behavior depends on the asset type:
- If the payout is in TON or Extra Currency, it will be an internal message with the notification opcode, and the corresponding TON or Extra Currency tokens will be attached to it.
- If the payout is in Jetton, the notification - still encapsulating the user’s
custom_payload
- will be sent aforward_payload
within thejetton_transfer
.