Requesting Order Creation Transaction
Placing a cross-chain order on the deBridge Liquidity Network (DLN) actually means calling the DLN smart contract on the source chain. The transaction call must provide a wide range of parameters representing the order, including but not limited to: the give and take offers, recipient address, order authorities' addresses.
Additionally, the spread between the give offer (how much asset the user is selling) and the take offer (how much asset the user is buying) must be reasonably profitable to incentivize a solver to fulfill it. The thing is that it must not only reflect the current market exchange rate, but also include relevant fees and expenses:
the optional affiliate fee,
the DLN protocol fee,
the taker's margin fee,
the operating expenses that a solver would have to pay during and after order fulfillment (this includes solver's gas costs for filling an order on the destination chain, and for claiming order fulfillment on the source chain).
Preparing such a wide range of different variables could be a very sophisticated thing, which the API's create-tx endpoint takes off the developers.
The endpoint accepts several groups of parameters explained below.
Directional parameters
This group of parameters explain the source and destination chain and tokens: the input asset a user is selling on the source chain, and the output asset a user is buying on the destination chain.
| Parameter | Example value | Description |
|---|---|---|
|
| The internal |
|
| The address of the input token (a token a user is selling) |
|
| The internal |
|
| The address of the output token (a token a user is buying) |
Offer parameters
This group of parameters specify the selling and buying amounts, and how the API calculates a reasonably profitable market order.
| Parameter | Example value | Description |
|---|---|---|
|
| The amount of input token the user is selling, with decimals. It can be set to |
|
| The amount of output token the user is buying. It is recommended to let the API calculate the reasonable outcome automatically by setting this parameter to |
|
| Recommended. Moves the calculated amount of operating expenses (see above) out of the spread and adds it on top the amount of input token. |
Authorities and recipient addresses
This group of optional parameters define entities who are responsible for changing order on-chain, as well as how would be the recipient of the funds upon order fulfillment. Typically, a users' wallet addresses must be used to fill them.
Mind that all of these parameters are optional to the create-tx endpoint, making it possible to use it even when a user's wallet address is not available (e.g., until the wallet is being connected to the dApp). However, in this case API won't return a transaction call that can be signed and submitted to the blockchain.
Ensure that the address specified as the dstChainOrderAuthorityAddress parameter is accessible by the user. Otherwise, there is a risk of an order (and funds) being stuck forever due to inability to initiate an order cancellation procedure.
| Parameter | Example value | Description |
|---|---|---|
|
| the address (usually, a user wallet's address) on the source chain who is authorised to patch the order and receive funds back during order cancellation |
️ |
| the address (usually, a user wallet's address) on the destination chain who is authorised to patch and cancel the order |
️ |
| the address on the destination chain where the bought amount of output asset would get transferred to upon order fulfillment |
Affiliate fee parameters
| Parameter | Value | Description |
|---|---|---|
|
| Percent of the input token amount to cut off in favor of the given affiliate fee recipient during order creation. |
|
| the address on the source chain where the accrued affiliate fee would be transferred to after the order is being fulfilled and unlocked |
Compiling it all together, a call to the create-tx endpoint produces a JSON-formatted response with several properties. Here is the example request:
https://dln.debridge.finance/v1.0/dln/order/create-tx?srcChainId=56&srcChainTokenIn=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d&srcChainTokenInAmount=100000000000000000000&dstChainId=43114&dstChainTokenOut=0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7&dstChainTokenOutAmount=auto&dstChainTokenOutRecipient=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&srcChainOrderAuthorityAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&dstChainOrderAuthorityAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&affiliateFeePercent=0.1&affiliateFeeRecipient=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
Notable response fields:
estimationfield gives an in-depth explanation on how the API has calculated the amount of input and output tokens of an order.txfield contains the transaction call that has to be signed and submitted by a user. This field is only available if all authorities and recipient addresses were specified upon request.orderIdfield contains the deterministic ID of the order that would get placed when the transaction call gets included on the blockchainorder.approximateFulfillmentDelayis the approximate time (in seconds) the order would get filled after the transaction call gets included on the blockchain
Important considerations
The create-tx endpoint is intended to be used for both estimation and transaction construction: safely use it without authorities and recipient addresses when user's wallet address is not available but the amount of input or output token should be suggested to a user; once addresses are available and specified, the same request should be used to retrieve a transaction call.
It is advised to let the API calculate the reasonable outcome automatically by setting dstChainTokenOutAmount parameter to auto on both calls. This ensures the order remain profitable for solvers after it gets placed on the blockchain.
It is advised to expire the order creation transaction after 30 seconds since it has been retrieved from the API to ensure the order remain profitable for solvers after it gets placed the blockchain.
Last updated