Placing orders
Estimating the order
First, decide which tokens you are willing to sell on the source chain and which tokens you are willing to buy on the destination chain. Say, you're selling 1 wBTC on Ethereum and buying a reasonable amount of DOGE on BNB.
The deBridge Liquidity Network Protocol is completely asset-agnostic, meaning that you can place an order giving wBTC or WETH, or any other asset. However, solvers mainly hold USDC and ETH on their wallets' balance and execute only the orders where the input token is either a USDC token or a native ETH. Thus, for a quick fulfillment of the order placed in the deBridge Liquidity Network Protocol, it's recommended to pre-swap your input token to any of these reserve-ready tokens before placing an order.
On the other hand, DLN is an open market, so anyone can become a solver and execute orders with custom input tokens or profitability.
Let's assume you've swapped your 1 wBTC to 25,000 USDC which will be then used upon order creation.
Second, calculate the reasonable amount of tokens you are willing to receive on the destination chain upon order fulfillment according to the current market condition and the protocol fees. Simply speaking, give at least 4 bps (DLN protocol fee) + 4 bps (Taker's incentive) = 8 bps + $6 (expected gas expenses taken by the taker to fulfill the order). This amount is laid in as a spread of the limit order, or margin between input and output tokens. Getting back to the example, the math below gives us a reasonable amount of DOGE we are willing to take:
Copy
Third, make sure you have enough Ether to cover the protocol fee, which is being taken by DlnSource
smart contract for order creation. You are advised to query DlnSource.globalFixedNativeFee()
function to retrieve this value. For example, the globalFixedNativeFee
value for the Ethereum blockchain would be 1000000000000000
, which resolves to 0.001 ETH.
Placing order on-chain
To place an order,
set USDC token approval to allow the
DlnSource
contract spend tokens on your behalf,call the
DlnSource.createOrder()
method:
Copy
Preparing an OrderCreation
struct
OrderCreation
has the following structure:
Preparing other arguments
Subsequent arguments of the createOrder()
function can be safely omitted by specifying default values:
_affiliateFee
can be set to empty bytes array (0x
); this argument allows you to ask the protocol to keep the given amount as an affiliate fee in favor of affiliate beneficiary and release it whenever an order is completely fulfilled. This is useful if you built a protocol and place orders on behalf of your users. To do so, concat the address and the amount into a single bytes array, whose length is expected to be exactly 52 bytes._referralCode
can be set to zero (0
); it is an invitation code to identify your transaction. If you don't have it, you can get one by pressing the INVITE FRIENDS button at app.debridge.finance. Governance may thank you later for being an early builder._permitEnvelope
can be set to empty bytes array (0x
); it allows you to use an EIP-2612-compliant signed approval so you don't have to give a prior spending approval to allow theDlnSource
contract to spend tokens on your behalf. This argument acceptsamount
+deadline
+signature
as a single bytes array
Making a call
Once all arguments are prepared, you are ready to make the call. Make sure you supply the exact amount of native blockchain currency to the value
to cover the DLN protocol fee (globalFixedNativeFee
).
Whenever the call to DlnSource.createOrder()
succeeded, it would return the orderId
which can be used to track, cancel and fulfill the order.
Additionally, the CreatedOrder
event is emitted:
which contains an Order
structure that is important to know to be able to fulfill or cancel this order.
Tracking order status
There is no way to know the order status on the chain where the order was placed. You need to switch to the chain it is intended to be fulfilled on (the takeChainId
property of the order).
You have two options to programmatically find whenever an order has been fulfilled or cancelled on the destination chain (not the chain where you placed it): either by querying the DlnDestination.takeOrders()
getter method, or by capturing the FulfilledOrder()
and SentOrderCancel()
events emitted by the DlnDestination
contract.
The DlnDestination.takeOrders()
getter method is defined as follows:
returns the status
property which indicates:
status=0
: the given order is neither fulfilled nor cancelled,status=1
: the given order is successfully fulfilled (funds sent to the given receiver)status=2
: unlock procedure has been initiated upon fulfillment to unlock the given funds on the source chain, as per taker requeststatus=3
: cancel procedure has been initiated to unlock the given funds on the source chain, as per order'sorderAuthorityAddressDst
request
Alternatively, you can capture events emitted by the DlnDestination
contact:
The FulfilledOrder
event is emitted whenever the order has been successfully fulfilled.
The SentOrderCancel
event is emitted whenever the cancel procedure has been initiated, as per order's orderAuthorityAddressDst
request.
Canceling order
The only way to cancel the order is to initiate the cancellation procedure on the chain it was intended to be fulfilled on (the takeChainId
property of the order). During the cancellation process, the order is marked as cancelled (to prevent further fulfillment) and a cross-chain message is sent through the deBridge cross-chain messaging infrastructure to the DlnSource
contract on the source chain to unlock the given funds. The funds locked on the source chain are returned in full including affiliate and protocol fees.
To initiate the cancellation procedure, call the DlnDestination.sendEvmOrderCancel()
method on the destination chain as follows:
mind that only an
orderAuthorityAddressDst
address specified during the order creation is allowed to perform this call for the given order;you need to cover the deBridge cross-chain messaging protocol fee (measured in the blockchain native currency where the message is being sent from) to make a cancellation message accepted. Consider looking at the details on retrieving the deBridge protocol fee;
for the
_order
argument, use theOrder
structure obtained from theCreatedOrder()
upon order creation;for the
_cancelBeneficiary
argument, use the address you'd like the given funds to be unlocked to on the source chain. Whenever theallowedCancelBeneficiarySrc
has been explicitly provided upon order creation, you are only allowed to use that value;for the
_executionFee
argument, specify the amount of native blockchain currency (in addition to the deBridge protocol fee) to provide an incentive to keepers for the successful claim of the cross-chain message on the destination chain. In other words, this is a prepayment for potential gas expenses on the destination chain, that will be transferred by the protocol. Otherwise, you'd need to find the cross-chain transaction in the deExplorer and claim it manually. Consider understanding how the cross-chain call is handled.
Finally, you are ready to initiate a cancellation procedure:
Last updated