diff --git a/docs/.gitbook/assets/B (1).png b/docs/.gitbook/assets/B (1).png new file mode 100644 index 00000000..d4207c3b Binary files /dev/null and b/docs/.gitbook/assets/B (1).png differ diff --git a/docs/.gitbook/assets/B.png b/docs/.gitbook/assets/B.png index d4207c3b..791d2cc0 100644 Binary files a/docs/.gitbook/assets/B.png and b/docs/.gitbook/assets/B.png differ diff --git a/docs/.gitbook/assets/Bridging and Networking (4).png b/docs/.gitbook/assets/Bridging and Networking (4).png new file mode 100644 index 00000000..a7b8938d Binary files /dev/null and b/docs/.gitbook/assets/Bridging and Networking (4).png differ diff --git a/docs/.gitbook/assets/Header (1).png b/docs/.gitbook/assets/Header (1).png new file mode 100644 index 00000000..8819b895 Binary files /dev/null and b/docs/.gitbook/assets/Header (1).png differ diff --git a/docs/.gitbook/assets/Header (2).png b/docs/.gitbook/assets/Header (2).png new file mode 100644 index 00000000..b05a5d6d Binary files /dev/null and b/docs/.gitbook/assets/Header (2).png differ diff --git a/docs/.gitbook/assets/Header (3).png b/docs/.gitbook/assets/Header (3).png new file mode 100644 index 00000000..c51a707d Binary files /dev/null and b/docs/.gitbook/assets/Header (3).png differ diff --git a/docs/.gitbook/assets/Header (4).png b/docs/.gitbook/assets/Header (4).png new file mode 100644 index 00000000..c6a97108 Binary files /dev/null and b/docs/.gitbook/assets/Header (4).png differ diff --git a/docs/.gitbook/assets/Header.png b/docs/.gitbook/assets/Header.png new file mode 100644 index 00000000..6a19f953 Binary files /dev/null and b/docs/.gitbook/assets/Header.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 1.png b/docs/.gitbook/assets/Slide 16_9 - 1.png new file mode 100644 index 00000000..eb77f278 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 1.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 10.png b/docs/.gitbook/assets/Slide 16_9 - 10.png new file mode 100644 index 00000000..91eafdbc Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 10.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 11.png b/docs/.gitbook/assets/Slide 16_9 - 11.png new file mode 100644 index 00000000..02692b21 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 11.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 12.png b/docs/.gitbook/assets/Slide 16_9 - 12.png new file mode 100644 index 00000000..2b4fa1df Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 12.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 15.png b/docs/.gitbook/assets/Slide 16_9 - 15.png new file mode 100644 index 00000000..c3ad7528 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 15.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 16.png b/docs/.gitbook/assets/Slide 16_9 - 16.png new file mode 100644 index 00000000..8fc11941 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 16.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 2.png b/docs/.gitbook/assets/Slide 16_9 - 2.png new file mode 100644 index 00000000..8b41b328 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 2.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 3.png b/docs/.gitbook/assets/Slide 16_9 - 3.png new file mode 100644 index 00000000..309765d4 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 3.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 4.png b/docs/.gitbook/assets/Slide 16_9 - 4.png new file mode 100644 index 00000000..bdbae2e3 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 4.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 5.png b/docs/.gitbook/assets/Slide 16_9 - 5.png new file mode 100644 index 00000000..58580363 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 5.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 6.png b/docs/.gitbook/assets/Slide 16_9 - 6.png new file mode 100644 index 00000000..524a74cd Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 6.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 7.png b/docs/.gitbook/assets/Slide 16_9 - 7.png new file mode 100644 index 00000000..d4999563 Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 7.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 8.png b/docs/.gitbook/assets/Slide 16_9 - 8.png new file mode 100644 index 00000000..b3c48cad Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 8.png differ diff --git a/docs/.gitbook/assets/Slide 16_9 - 9.png b/docs/.gitbook/assets/Slide 16_9 - 9.png new file mode 100644 index 00000000..e225ad0b Binary files /dev/null and b/docs/.gitbook/assets/Slide 16_9 - 9.png differ diff --git a/docs/.gitbook/assets/getting a quote b/docs/.gitbook/assets/getting a quote new file mode 100644 index 00000000..15d0dc8e --- /dev/null +++ b/docs/.gitbook/assets/getting a quote @@ -0,0 +1,129 @@ +Getting a Quote | deSwap Liquidity Network (DLN)

Getting a Quote

/quote endpoint of DNL API should be used only to display outcomes of the trades when the address of the user is unknown (e.g. to let the user see prices of cross-chain trades before he connects the wallet to the Dapp).

Whenever an address is known, make sure to call /create-tx directly.

To place an order that would be reasonably profitable to incentivize a taker to fulfill it, a quote must not only reflect the current market exchange rate but also include relevant fees: the affiliate fee (in case you are going to collect an affiliate fee), the DLN protocol fee, the taker's margin fee; additionally, a quote must cover all implicit operating expenses incurred by a taker during and after order fulfillment (that includes Taker's gas costs for fulfillment and unlock of liquidity in the source chain).

The /v1.0/dln/order/quote endpoint performs all necessary calculations to provide the best reasonable quote for the given input.

Let's get a quote for our use-case by calling the /v1.0/dln/order/quote endpoint with the following parameter values:

ParameterValueDescription

srcChainId

56

specifies the ID of the BNB Chain as the chain where an order would be placed

srcChainTokenIn

0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d

sets the input token (the user is willing to give) to the USDC token address on the BNB Chain

srcChainTokenInAmount

100000000000000000000

specifies the desired input amount: since the USDC token contract uses 18 decimals (the number of digits that come after the decimal place when displaying token values on-screen), the simple math: 100*10^18 leads to 100000000000000000000 as the value representing 100 USDC tokens

dstChainId

43114

specified the Avalanche network chain ID as the destination chain where an order should be fulfilled

dstChainTokenOut

0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7

sets the output token (the user is willing to take) to the USDT token address on Avalanche

prependOperatingExpense

true

asks the API to add the approximate amount of operating expenses to the amount of input token before making a quote

affiliateFeePercent

0.1

asks the order to accrue the given share of input amount, which would be paid after an order gets fulfilled and unlocked

Calling the endpoint:

https://api.dln.trade/v1.0/dln/order/quote?srcChainId=56&srcChainTokenIn=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d&srcChainTokenInAmount=100000000000000000000&dstChainId=43114&dstChainTokenOut=0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7&prependOperatingExpenses=true&affiliateFeePercent=0.1

gives a response with the recommended amount of input token, and several details describing how it has been calculated. The recommended amount of the output token (USDT in our case) available in the estimation.dstChainTokenOut.recommendedAmount property — this is the amount that can be suggested to a user for explicit approval before placing an order.

At the time of writing, the response contains the following values:

{
+    "estimation": {
+            "srcChainTokenIn": {
+                    "address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d",
+                    "decimals": 18,
+                    "name": "USD Coin",
+                    "symbol": "USDC",
+                    "chainId": 56,
+                    ,
+                    ,
+                    "approximateOperatingExpense": "722632000000000000",
+            },
+            "dstChainTokenOut": {
+                    "address": "0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7",
+                    "decimals": 6,
+                    "name": "TetherToken",
+                    "symbol": "USDt",
+                    "chainId": 43114,
+                    "amount": "99623050",
+                    
+            },
+            
+            [...]
+    },
+    
+    [...],
+        
+    "tx": {
+        "allowanceTarget": "0xeF4fB24aD0916217251F553c0596F8Edc630EB66",
+        "allowanceValue": "100722632000000000000"
+    },
+}

This response states that executing an order to swap 100 USDC on BNB Chain to USDT on Avalanche requires approximately 0.722632 USDC, so this has been added to the input amount, resulting 100.722632 USDC to be charged from the user upon order creation.

Additionally, 0.100722632 USDC is accrued as an affiliate fee upon order creation.

The affiliate fee is paid only after the order gets fulfilled, and after the taker has unlocked the order in the source chain.

The most important part is the recommended amount of the output token: the API endpoint assumes that takers would be incentivized to fulfill an order with the given input at the time of the request if taking 99.623050 USDT. Not bad for a cross-chain swap!

If a user is comfortable with the quote, a transaction to create a limit order with the given quote can be requested.

PreviousQuick Start GuideNextRequesting Order Creation Transaction

Last updated

\ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 21fb133e..44ccd64f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,10 +1,29 @@ -# Introduction +--- +cover: .gitbook/assets/Header (2).png +coverY: 0 +layout: + cover: + visible: true + size: hero + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true +--- -
+# Introduction -**deBridge is** **a high-performance and** **secure interoperability layer for Web3** that enables decentralized transfers of arbitrary messages and value between blockchains. The validation of cross-chain transactions is performed by a network of independent validators who are elected by and work for deBridge governance. Validators maintain the blockchain infrastructure and each run a deBridge node to sign all transactions that pass through deBridge smart contracts in different blockchains. +**deBridge is DeFi's internet of liquidity**, enabling real-time movement of assets and information across the DeFi landscape. Without the bottlenecks and risks of liquidity pools, deBridge can power all type of cross-chain interactions with deep liquidity, tight spreads, and guaranteed rates.\ +\ +The validation of cross-chain transactions is performed by a network of independent validators who are elected by and work for deBridge governance. Validators maintain the blockchain infrastructure and each run a deBridge node to sign all transactions that pass through deBridge smart contracts on different supported blockchains. -[Delegated staking and slashing](the-core-protocol/slashing-and-delegated-staking.md) mechanics act as a backbone for protocol security and provide economic disincentives for validators to collude. +[Delegated staking and slashing](the-debridge-messaging-protocol/slashing-and-delegated-staking.md) mechanics act as a backbone for protocol security and provide economic disincentives for validators to collude. The deBridge protocol is an infrastructure platform and a framework for: @@ -22,7 +41,7 @@ Projects can integrate with deBridge infrastructure to tap into the various cros * Build new types of cross-chain applications and primitives * Enable global accessibility by letting users and protocols from other chains seamlessly interact with the protocol -Our [getting-started.md](build-with-debridge/getting-started.md "mention") guide is a great starting point that covers all topics needed to start building cross-chain interactions through the deBridge protocol and its infrastructure. +Our [building-an-evm-based-dapp](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/ "mention") guide is a great starting point that covers all topics needed to start building cross-chain interactions through the deBridge protocol and its infrastructure. The deBridge protocol will be controlled by a DAO with decentralized governance which allows all token holders to participate in future growth, have a word in the future decisions regarding protocol parameters, and participate in treasury management. @@ -45,10 +64,10 @@ Facebook: [https://www.facebook.com/deBridgeFinance](https://www.facebook.com/de ## Quick Start -{% content-ref url="the-core-protocol/protocol-overview.md" %} -[protocol-overview.md](the-core-protocol/protocol-overview.md) +{% content-ref url="the-debridge-messaging-protocol/protocol-overview.md" %} +[protocol-overview.md](the-debridge-messaging-protocol/protocol-overview.md) {% endcontent-ref %} -{% content-ref url="build-with-debridge/getting-started.md" %} -[getting-started.md](build-with-debridge/getting-started.md) +{% content-ref url="the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/" %} +[building-an-evm-based-dapp](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/) {% endcontent-ref %} diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index cd4fcc7f..c925a4b4 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -2,31 +2,68 @@ * [Introduction](README.md) -## The Core Protocol - -* [Protocol Overview](the-core-protocol/protocol-overview.md) -* [Slashing and Delegated Staking](the-core-protocol/slashing-and-delegated-staking.md) -* [Fees and supported chains](the-core-protocol/fees-and-supported-chains.md) -* [Security](the-core-protocol/security.md) - -## 🛠️ Build with deBridge - -* [Getting started](build-with-debridge/getting-started.md) -* [Getting started with Solana](build-with-debridge/getting-started-with-solana/README.md) - * [On-Chain external call preparation for Solana](build-with-debridge/getting-started-with-solana/on-chain-external-call-preparation-for-solana.md) - * [Off-chain external call preparation for Solana](build-with-debridge/getting-started-with-solana/off-chain-external-call-preparation-for-solana.md) -* [Lifecycle of a cross-chain call](build-with-debridge/lifecycle-of-a-cross-chain-call.md) -* [Advanced topics](build-with-debridge/advanced-topics/README.md) - * [Gathering data for the claim](build-with-debridge/advanced-topics/gathering-data-for-the-claim.md) -* [Smart contract interface](build-with-debridge/smart-contract-interface.md) -* [Development tools](build-with-debridge.md) - -## 🔁 Cross-chain bridging and value transfers - -* [deBridge API Quick Start Guide](cross-chain-bridging-and-value-transfers/debridge-api-quick-start-guide.md) -* [Cross-Chain Swaps Liquidity](cross-chain-bridging-and-value-transfers/cross-chain-swaps-liquidity.md) -* [Custom Linking](cross-chain-bridging-and-value-transfers/custom-linking.md) -* [deBridge Widget](cross-chain-bridging-and-value-transfers/debridge-widget.md) +## The deBridge Messaging Protocol + +* [Protocol Overview](the-debridge-messaging-protocol/protocol-overview.md) +* [Fees and Supported Chains](the-debridge-messaging-protocol/fees-and-supported-chains.md) +* [🟢 Deployed Contracts](the-debridge-messaging-protocol/deployed-contracts.md) +* [Development Guides](the-debridge-messaging-protocol/development-guides/README.md) + * [Building an EVM-based dApp](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/README.md) + * [EVM smart contract interfaces](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/README.md) + * [Interfaces](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/README.md) + * [ICallProxy](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/icallproxy.md) + * [IDeBridgeGate](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgegate.md) + * [IDeBridgeToken](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgetoken.md) + * [IDeBridgeTokenDeployer](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgetokendeployer.md) + * [IOraclesManager](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/ioraclesmanager.md) + * [ISignatureVerifier](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/isignatureverifier.md) + * [IWethGate](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/iwethgate.md) + * [Libraries](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/libraries/README.md) + * [Flags](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/libraries/flags.md) + * [Periphery](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/README.md) + * [CallProxy](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/callproxy.md) + * [DeBridgeToken](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/debridgetoken.md) + * [DeBridgeTokenProxy](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/debridgetokenproxy.md) + * [SimpleFeeProxy](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/simplefeeproxy.md) + * [Transfers](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/README.md) + * [DeBridgeGate](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/debridgegate.md) + * [DeBridgeTokenDeployer](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/debridgetokendeployer.md) + * [OraclesManager](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/oraclesmanager.md) + * [SignatureVerifier](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/signatureverifier.md) + * [WethGate](the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/wethgate.md) + * [Sending cross-chain messages from Solana](the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/README.md) + * [On-Chain external call preparation for Solana](the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/on-chain-external-call-preparation-for-solana.md) + * [Off-chain external call preparation for Solana](the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/off-chain-external-call-preparation-for-solana.md) + * [Lifecycle of a cross-chain call](the-debridge-messaging-protocol/development-guides/lifecycle-of-a-cross-chain-call.md) + * [Gathering data for the claim](the-debridge-messaging-protocol/development-guides/gathering-data-for-the-claim.md) +* [Development Tools](the-debridge-messaging-protocol/development-tools.md) +* [Security](the-debridge-messaging-protocol/security.md) +* [Slashing and Delegated Staking](the-debridge-messaging-protocol/slashing-and-delegated-staking.md) + +## 🔁 DLN: The deBridge Liquidity Network Protocol + +* [Introduction](dln-the-debridge-liquidity-network-protocol/introduction.md) +* [Protocol Overview](dln-the-debridge-liquidity-network-protocol/protocol-overview.md) +* [Fees and Supported Chains](dln-the-debridge-liquidity-network-protocol/fees-and-supported-chains.md) +* [🟢 Deployed Contracts](dln-the-debridge-liquidity-network-protocol/deployed-contracts.md) +* [Market and Limit Orders](dln-the-debridge-liquidity-network-protocol/market-and-limit-orders.md) +* [Interacting with smart contracts](dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/README.md) + * [Introduction](dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/introduction.md) + * [Placing orders](dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/placing-orders.md) + * [Filling orders](dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/filling-orders.md) + * [Withdrawing Affiliate Fees](dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/withdrawing-affiliate-fees.md) + * [Creating Calldata for Solana](dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/creating-calldata-for-solana.md) +* [Interacting with the API](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/README.md) + * [Quick Start Guide](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/quick-start-guide.md) + * [Getting a Quote](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/getting-a-quote.md) + * [Requesting Order Creation Transaction](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/requesting-order-creation-transaction.md) + * [Submitting an Order Creation Transaction](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/submitting-an-order-creation-transaction.md) + * [Tracking a Status of the Order](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/tracking-a-status-of-the-order.md) + * [Cancelling the Order](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/cancelling-the-order.md) + * [Affiliate fees](dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/affiliate-fees.md) +* [Interacting with the deBridge App](dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/README.md) + * [Custom Linking](dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/custom-linking.md) +* [deBridge Widget](dln-the-debridge-liquidity-network-protocol/debridge-widget.md) ## 💸 dePort @@ -42,31 +79,6 @@ * [Getting started](debridge-iaas/getting-started.md) -## Contracts - -* [📑 Mainnet Addresses](contracts/mainnet-addresses.md) -* [Interfaces](contracts/interfaces/README.md) - * [ICallProxy](contracts/interfaces/ICallProxy.md) - * [IDeBridgeGate](contracts/interfaces/IDeBridgeGate.md) - * [IDeBridgeToken](contracts/interfaces/IDeBridgeToken.md) - * [IDeBridgeTokenDeployer](contracts/interfaces/IDeBridgeTokenDeployer.md) - * [IOraclesManager](contracts/interfaces/IOraclesManager.md) - * [ISignatureVerifier](contracts/interfaces/ISignatureVerifier.md) - * [IWethGate](contracts/interfaces/IWethGate.md) -* [Libraries](contracts/libraries/README.md) - * [Flags](contracts/libraries/Flags.md) -* [Periphery](contracts/periphery/README.md) - * [CallProxy](contracts/periphery/CallProxy.md) - * [DeBridgeToken](contracts/periphery/DeBridgeToken.md) - * [DeBridgeTokenProxy](contracts/periphery/DeBridgeTokenProxy.md) - * [SimpleFeeProxy](contracts/periphery/SimpleFeeProxy.md) -* [Transfers](contracts/transfers/README.md) - * [DeBridgeGate](contracts/transfers/DeBridgeGate.md) - * [DeBridgeTokenDeployer](contracts/transfers/DeBridgeTokenDeployer.md) - * [OraclesManager](contracts/transfers/OraclesManager.md) - * [SignatureVerifier](contracts/transfers/SignatureVerifier.md) - * [WethGate](contracts/transfers/WethGate.md) - ## External Links * [deBridge Use Cases](external-links/debridge-use-cases.md) diff --git a/docs/build-with-debridge/advanced-topics/README.md b/docs/build-with-debridge/advanced-topics/README.md deleted file mode 100644 index f0b10d2c..00000000 --- a/docs/build-with-debridge/advanced-topics/README.md +++ /dev/null @@ -1,2 +0,0 @@ -# Advanced topics - diff --git a/docs/contracts/interfaces/README.md b/docs/contracts/interfaces/README.md deleted file mode 100644 index 6432dc62..00000000 --- a/docs/contracts/interfaces/README.md +++ /dev/null @@ -1,8 +0,0 @@ - -* [ICallProxy](ICallProxy.md) -* [IDeBridgeGate](IDeBridgeGate.md) -* [IDeBridgeToken](IDeBridgeToken.md) -* [IDeBridgeTokenDeployer](IDeBridgeTokenDeployer.md) -* [IOraclesManager](IOraclesManager.md) -* [ISignatureVerifier](ISignatureVerifier.md) -* [IWethGate](IWethGate.md) \ No newline at end of file diff --git a/docs/contracts/libraries/README.md b/docs/contracts/libraries/README.md deleted file mode 100644 index b066b971..00000000 --- a/docs/contracts/libraries/README.md +++ /dev/null @@ -1,2 +0,0 @@ - -* [Flags](Flags.md) \ No newline at end of file diff --git a/docs/contracts/periphery/README.md b/docs/contracts/periphery/README.md deleted file mode 100644 index 90128120..00000000 --- a/docs/contracts/periphery/README.md +++ /dev/null @@ -1,5 +0,0 @@ - -* [CallProxy](CallProxy.md) -* [DeBridgeToken](DeBridgeToken.md) -* [DeBridgeTokenProxy](DeBridgeTokenProxy.md) -* [SimpleFeeProxy](SimpleFeeProxy.md) \ No newline at end of file diff --git a/docs/contracts/transfers/README.md b/docs/contracts/transfers/README.md deleted file mode 100644 index 6e4677ea..00000000 --- a/docs/contracts/transfers/README.md +++ /dev/null @@ -1,6 +0,0 @@ - -* [DeBridgeGate](DeBridgeGate.md) -* [DeBridgeTokenDeployer](DeBridgeTokenDeployer.md) -* [OraclesManager](OraclesManager.md) -* [SignatureVerifier](SignatureVerifier.md) -* [WethGate](WethGate.md) \ No newline at end of file diff --git a/docs/cross-chain-bridging-and-value-transfers/cross-chain-swaps-liquidity.md b/docs/cross-chain-bridging-and-value-transfers/cross-chain-swaps-liquidity.md deleted file mode 100644 index 5bcf2ebb..00000000 --- a/docs/cross-chain-bridging-and-value-transfers/cross-chain-swaps-liquidity.md +++ /dev/null @@ -1,120 +0,0 @@ -# Cross-Chain Swaps Liquidity - -{% hint style="info" %} -[deSwap App](https://app.debridge.finance/deswap) and API were migrated to [DLN](https://dln.trade/) — a high-performance cross-chain trading infrastructure built on deBridge with a unique 0-TVL design (no liquidity pools). - -Read the full announcement here: [https://twitter.com/deBridgeFinance/status/1655914135488696322](https://twitter.com/deBridgeFinance/status/1655914135488696322) - -If you've provided liquidity to the deSwap pools listed below, please withdraw it -{% endhint %} - -## **deSwap cross-chain pools at Curve** - -deBridge is a decentralized infrastructure that is fully composable with the existing DeFi ecosystem. That’s why we don’t need to invent our own AMM or DEX, but just create liquidity pools for deAssets in existing DEXs. In every blockchain supported by deBridge, there will be a liquidity pool for deUSDC at Curve or protocols that support the concept of the stable swap. - -Cross-chain swaps are one of the applications built on top of deBridge infrastructure that enables users to perform swaps from any asset on one chain to any asset on another. - -Here are the instructions on how to deposit liquidity into the pool for each blockchain/L2. - - - -| Blockchain/L2 | Link | Pool address | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -| Arbitrum (deUSDC) | [https://arbitrum.curve.fi/factory/17](https://arbitrum.curve.fi/factory/17) | [0x76b44e0cf9bd024dbed09e1785df295d59770138](https://arbiscan.io/address/0x76b44e0cf9bd024dbed09e1785df295d59770138) | -| Arbitrum (deETH) | [https://arbitrum.curve.fi/factory/15](https://arbitrum.curve.fi/factory/15) | [0x0a824b5d4c96ea0ec46306efbd34bf88fe1277e0](https://arbiscan.io/address/0x0a824b5d4c96ea0ec46306efbd34bf88fe1277e0) | -| Polygon (deUSDC) | [https://polygon.curve.fi/factory/111](https://polygon.curve.fi/factory/111) | [0xda43bfd7ecc6835aa6f1761ced30b986a574c0d2](https://polygonscan.com/address/0xda43bfd7ecc6835aa6f1761ced30b986a574c0d2) | -| BNB Chain (deUSDC) | [https://ellipsis.finance/pool/0x5A7d2F9595eA00938F3B5BA1f97a85274f20b96c](https://ellipsis.finance/pool/0x5A7d2F9595eA00938F3B5BA1f97a85274f20b96c) | [0x5A7d2F9595eA00938F3B5BA1f97a85274f20b96c](https://bscscan.com/address/0x5A7d2F9595eA00938F3B5BA1f97a85274f20b96c) | -| Avalanche (deUSDC) | [https://avax.curve.fi/factory/61](https://avax.curve.fi/factory/61) | [0xd39016475200ab8957e9c772c949ef54bda69111](https://snowtrace.io/address/0xd39016475200ab8957e9c772c949ef54bda69111) | - -### **Arbitrum deUSDC/2CRV pool** - -This is a stablecoin pool at Curve that contains deUSDC (USDC bridged through deBridge) paired with 2CRV - Curve token that represents the basket of two stable coins (USDT+USDC) - -In case you want to deposit $X amount of liquidity into this pool, please bridge half ($X/2) amount of USDC from Ethereum to deUSDC in Arbitrum through [dePort](https://app.debridge.finance/deport). The other half should be bridged through Arbitrum’s default bridge [https://bridge.arbitrum.io/](https://bridge.arbitrum.io/) in the form of USDT or USDC. - -_Be aware that you will need to have some ETH on your wallet in Arbitrum in order to cover gas costs to broadcast the transaction._ - -Once you have deUSDC and USDC/USDT in your wallet balance on Arbitrum (you can check through [https://arbiscan.io/](https://arbiscan.io/)), you can deposit the liquidity at Curve. - -1. Go to the Curve website of the pool: [https://arbitrum.curve.fi/factory/17/deposit](https://arbitrum.curve.fi/factory/17/deposit) -2. Connect your wallet - -![](<../.gitbook/assets/Screen Shot 2022-02-01 at 20.45.28.png>) - -3\. Deposit deUSDC and stable coins in a 1:1 ratio. - -4\. Confirm the transaction in your wallet. - -### **Arbitrum deETH/ETH pool** - -In case you want to deposit N amount of ETH into this pool, please bridge half (N/2) amount of ETH from Ethereum to deETH in Arbitrum through [dePort](https://app.debridge.finance/deport). The other half should be bridged through Arbitrum’s default bridge [https://bridge.arbitrum.io/](https://bridge.arbitrum.io/) - -Once you have deETH and ETH in your wallet balance on Arbitrum (you can check through [https://arbiscan.io/](https://arbiscan.io/)), you can deposit the liquidity at Curve. - -1. Go to the Curve website of the pool: [https://arbitrum.curve.fi/factory/15/deposit](https://arbitrum.curve.fi/factory/15/deposit). -2. Connect your wallet - -![](<../.gitbook/assets/Screen Shot 2022-02-01 at 20.51.01.png>) - -3\. Deposit deETH and ETH in a 1:1 ratio. - -4\. Confirm the transaction in your wallet. - -### **Polygon deUSDC/am3CRV pool** - -This is a stablecoin pool at Curve that contains deUSDC (USDC bridged through deBridge) paired with am3CRV - Curve token that represents the basket of two stable coins (USDT+USDC+DAI) - -In case you’d like to deposit $X amount of liquidity into this pool, please bridge half ($X/2) amount of USDC from Ethereum to deUSDC on Polygon through [dePort](https://app.debridge.finance/deport). The other half should be bridged through Polygon's default bridge [https://wallet.polygon.technology/bridge/](https://wallet.polygon.technology/bridge/) ) in the form of USDT or USDC or DAI. - -_Be aware that you will need to have some Matic in your wallet on Polygon in order to cover gas costs to broadcast the transaction._ - -Once you have deUSDC and USDC/USDT/DAI in your wallet balance on Polygon (you can check through [https://polygonscan.com/](https://polygonscan.com/)), you can deposit the liquidity at Curve. - -1. Go to the Curve website of the pool: [https://polygon.curve.fi/factory/111/deposit](https://polygon.curve.fi/factory/111/deposit) -2. Connect your wallet - -![](<../.gitbook/assets/Screen Shot 2022-02-01 at 20.53.40.png>) - -3\. Deposit deUSDC and stable coin in a 1:1 ratio. - -4\. Confirm the transaction in your wallet. - -### BNB Chain deUSDC/3EPS pool: - -This is a stablecoin pool at [Ellipsis Finance](https://ellipsis.finance/) — a fork of Curve on BNB Chain that is endorsed by the Curve core team. The pool contains deUSDC (USDC bridged through deBridge) paired with 3EPS – a meta token that represents the basket of three stable coins (USDT+USDC+BUSD) - -In case you want to deposit $X amount of liquidity into this pool, please bridge half ($X/2) amount of USDC from Ethereum to deUSDC on BNB Chain through [dePort](https://app.debridge.finance/deport). The other half should be bridged to BNB Chain through other bridges or centralized exchanges (e.g. Binance or FTX) in the form of [USDT](https://bscscan.com/token/0x55d398326f99059ff775485246999027b3197955), [USDC](https://bscscan.com/token/0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d), or [BUSD](https://bscscan.com/token/0xe9e7cea3dedca5984780bafc599bd69add087d56). - -_Be aware that you will need to have some BNB on your wallet in BNB Chain in order to cover gas costs to broadcast the transaction._ - -Once you have deUSDC and USDC/USDT/BUSD in your wallet balance on BNB Chain (you can check through [https://bscscan.com/](https://bscscan.com/)), you can deposit the liquidity at EPS: - -* Go to the EPS website of the pool: [https://ellipsis.finance/pool/4](https://ellipsis.finance/pool/4) -* Click “Add liquidity” and connect your wallet - - - -* Deposit deUSDC and stable coin in a 1:1 ratio -* Confirm transaction in your wallet - -Now LP tokens can be staked into the [Ellipsis Finance gauge](https://ellipsis.finance/pool/0x5A7d2F9595eA00938F3B5BA1f97a85274f20b96c) to receive additional $EPX rewards: - -![](<../.gitbook/assets/image (2) (1).png>) - -### **Avalanche deUSDC/av3CRV pool** - -This is a stablecoin pool at Curve that contains deUSDC (USDC bridged through deBridge) paired with av3CRV - Curve token that represents the basket of three stable coins (USDT+USDC+DAI) - -In case you’d like to deposit $X amount of liquidity into this pool, please bridge half ($X/2) amount of USDC from Ethereum to deUSDC on Avalanche through [dePort](https://app.debridge.finance/deport). The other half should be bridged through Avalanche's default bridge [https://bridge.avax.network/](https://bridge.avax.network/)) in the form of USDT or USDC or DAI. - -_Be aware that you will need to have some AVAX in your wallet on Avalanche in order to cover gas costs to broadcast the transaction._ - -Once you have deUSDC and USDC/USDT/DAI in your wallet balance on Avalanche (you can check through [https://snowtrace.io/](https://snowtrace.io/)), you can deposit the liquidity at Curve. - -1. Go to the Curve website of the pool: [https://avax.curve.fi/factory/61](https://avax.curve.fi/factory/61) -2. Connect your wallet - -![](<../.gitbook/assets/Screen Shot 2022-04-12 at 14.12.56.png>) - -**Now all is done and liquidity will be used for all the cross-chain swaps 🚀** - diff --git a/docs/cross-chain-bridging-and-value-transfers/debridge-api-quick-start-guide.md b/docs/cross-chain-bridging-and-value-transfers/debridge-api-quick-start-guide.md deleted file mode 100644 index 8a1a9cdb..00000000 --- a/docs/cross-chain-bridging-and-value-transfers/debridge-api-quick-start-guide.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -description: >- - Integrate decentralized cross-chain swaps between arbitrary assets into any - applications (web apps, wallets, dApps) in just a few lines of code. ---- - -# deBridge API Quick Start Guide - -{% hint style="warning" %} -[deSwap App](https://app.debridge.finance/deswap) and DLN are both utilizing the deBridge API which is high-performance cross-chain bridging and value transfer infrastructure built with deBridge with a unique 0-TVL design (no liquidity pools). - -Read the full announcement here: [https://twitter.com/deBridgeFinance/status/1655914135488696322](https://twitter.com/deBridgeFinance/status/1655914135488696322) - - - -deBridge Cross-chain bridging API is now available as part of DLN API found at docs.dln.trade: [https://docs.dln.trade/dln-api/quick-start-guide](https://docs.dln.trade/dln-api/quick-start-guide) -{% endhint %} diff --git a/docs/debridge-iaas/getting-started.md b/docs/debridge-iaas/getting-started.md index d0d44206..a7d0ec6a 100644 --- a/docs/debridge-iaas/getting-started.md +++ b/docs/debridge-iaas/getting-started.md @@ -2,10 +2,10 @@ ## deBridge IaaS -
- deBridge IaaS (Interoperability-as-a-Service) is the first service enabling complete cross-chain interoperability for any EVM or SVM blockchain ecosystems. It’s a turnkey solution that allows any chain to plug into deBridge infrastructure solving all three pillars of interoperability simultaneously including transfers of authenticated messages, cross-chain asset custody, and native high-performance value exchange (liquidity bridging). +
+ As a complete solution, deBridge IaaS can enable any chain to become fully composable within the global DeFi ecosystem, attracting developers, users, and liquidity from outside their ecosystem all with a subscription fee, paid on-chain. Blockchain ecosystems no longer have to solve each hurdle individually but instead can open up to global composability from day one. {% hint style="success" %} diff --git a/docs/deport/getting-started.md b/docs/deport/getting-started.md index 57904fdf..bb342f77 100644 --- a/docs/deport/getting-started.md +++ b/docs/deport/getting-started.md @@ -2,11 +2,11 @@ ## dePort -
+
-[**dePort**](https://app.debridge.finance/deport) is a native bridge for assets that allows protocols to bridge tokens and create utility for their synthetic representation (deTokens) in other chains. +[**dePort**](https://app.debridge.finance/deport) is a native bridge for assets that allows protocols to bridge tokens and create utility for their synthetic representation (deTokens) on other chains. -dePort utilizes a locking and minting approach where the native token is locked/unlocked in a deBridgeGate smart contract in the native chain and its synthetic representation (deAsset) is minted/burnt in secondary chains. +dePort utilizes a lock-and-mint approach where the native token is locked/unlocked in a deBridgeGate smart contract on the native (source) chain and its synthetic representation (deAsset) is minted/burnt in secondary (target) chains. For each asset, under the **native chain**, we assume the unique blockchain where the token was originally created. @@ -14,7 +14,7 @@ For each asset, under the **native chain**, we assume the unique blockchain wher ### Collateralization -Each of the tokens locked in the native chain have the associated wrapped asset on the target chains. By design, the protocol ensures that the total supply of each deAsset that can be minted in secondary chains is always 1:1 backed by the asset collateral locked in the deBridgeGate smart contract in the native chain. That provides a flawless user experience and guarantees that the user will never face a liquidity imbalance problem which is often encountered in other bridging solutions, where users face significant delays after they already locked liquidity in the bridge. +Each of the tokens locked in the native chain have the associated wrapped asset on the target chains. By design, the protocol ensures that the total supply of each deAsset that can be minted on secondary chains is always 1:1 backed by the asset collateral locked in the deBridgeGate smart contract on the native chain. That provides more secure and reliable user experience and guarantees that the user will not face a liquidity imbalance problem which has been encountered in other bridging solutions, where users face significant delays after they already locked liquidity in a bridge. ### Listing at deBridge diff --git a/docs/cross-chain-bridging-and-value-transfers/debridge-widget.md b/docs/dln-the-debridge-liquidity-network-protocol/debridge-widget.md similarity index 90% rename from docs/cross-chain-bridging-and-value-transfers/debridge-widget.md rename to docs/dln-the-debridge-liquidity-network-protocol/debridge-widget.md index e35f2a1b..f40a773c 100644 --- a/docs/cross-chain-bridging-and-value-transfers/debridge-widget.md +++ b/docs/dln-the-debridge-liquidity-network-protocol/debridge-widget.md @@ -4,9 +4,10 @@ deBridge Widget is available at [https://app.debridge.finance/widget](https://ap ### Getting Started with the deBridge Widget -With just a few lines of code, all projects and developers can embed a cross-chain exchange between arbitrary assets within your app (mobile app, website, dApp, etc.) based on the deBridge protocol. You can make the widget part of your app and you're fully free to customize colors, fonts, chains, and tokens according to your design and preferences. Here's an example: +With just a few lines of code, all projects and developers can embed a cross-chain exchange between arbitrary assets within your app (mobile app, website, dApp, etc.) based on the deBridge protocol. You can make the deBridge widget part of your app and you're fully free to customize colors, fonts, chains, and tokens according to your design and preferences. Here's an example:\ -![](<../.gitbook/assets/image (3).png>) + +
### **Requirements** @@ -97,7 +98,7 @@ fontFamily: string } ``` -![](https://t4717986.p.clickup-attachments.com/t4717986/a45292fd-c79e-424a-9689-837ff3f2e136/image.png) +
### deBridge Widget builder diff --git a/docs/dln-the-debridge-liquidity-network-protocol/deployed-contracts.md b/docs/dln-the-debridge-liquidity-network-protocol/deployed-contracts.md new file mode 100644 index 00000000..bf37e7e2 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/deployed-contracts.md @@ -0,0 +1,26 @@ +# 🟢 Deployed Contracts + +The following smart contracts have been deployed across supported chains to power DLN: + +### Solana + +| Smart contract | Address | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | +| `DlnSource` | [src5qyZHqTqecJV4aY6Cb6zDZLMDzrDKKezs22MPHr4](https://solscan.io/account/src5qyZHqTqecJV4aY6Cb6zDZLMDzrDKKezs22MPHr4) | Used to place orders on DLN | +| `DlnDestination` | [dst5MGcFPoBeREFAA5E3tU5ij8m5uVYwkzkSAbsLbNo](https://solscan.io/account/dst5MGcFPoBeREFAA5E3tU5ij8m5uVYwkzkSAbsLbNo) | Used to fulfill and cancel DLN orders | + +### EVM Chains + +| Smart contract | Address | Description | +| ---------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `DlnSource` | `0xeF4fB24aD0916217251F553c0596F8Edc630EB66` | Used to place orders on DLN | +| `DlnDestination` | `0xe7351fd770a37282b91d153ee690b63579d6dd7f` | Used to fulfill and cancel orders placed on DLN | +| `CrosschainForwarder` | `0x663dc15d3c1ac63ff12e45ab68fea3f0a883c251` | Intermediary smart contract used exclusively by the DLN API to sell input assets for trusted liquid assets prior order created, if necessary. | +| `ExternalCallExecutor` | `0xFC2CA4022d26AD4dCb3866ae30669669F6A28f19` | Used to accepting tokens and data to execute dln external calls | + +### **Contract ABIs** + +[DlnSource.abi.json](https://3251284410-files.gitbook.io/\~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8SH9Mg0oTRdKFNHxWvTP%2Fuploads%2F2Cg4HetCApwZBZxkThpT%2FDlnSource.abi.json?alt=media\&token=0bf21e5f-7511-4cc0-86a2-841a1bd70f3a) + +[DlnDestination.abi.json](https://3251284410-files.gitbook.io/\~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8SH9Mg0oTRdKFNHxWvTP%2Fuploads%2FyhXoBlUK16nqXPM3vSgM%2FDlnDestination.abi.json?alt=media\&token=397802d5-e1bf-4743-95fc-8d248210ed38) + diff --git a/docs/dln-the-debridge-liquidity-network-protocol/fees-and-supported-chains.md b/docs/dln-the-debridge-liquidity-network-protocol/fees-and-supported-chains.md new file mode 100644 index 00000000..d43d0f24 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/fees-and-supported-chains.md @@ -0,0 +1,28 @@ +# Fees and Supported Chains + +## Fees and supported chains + +deBridge charges a small fee when an order is created through `DlnSource` smart contracts. The fee is what users pay for confidence and decentralization. It consists of two parts: + +* A flat fee is paid in the native gas token of the chain where the order is created +* A variable fee of 4bps is paid in the input token + +| Chain (Chain id) | Chain Id | Flat Fee | +| ---------------- | --------- | ---------- | +| Arbitrum | 42161 | 0.001 ETH | +| Avalanche | 43114 | 0.05 AVAX | +| BNB Chain | 56 | 0.005 BNB | +| Ethereum | 1 | 0.001 ETH | +| Polygon | 137 | 0.5 MATIC | +| Solana | 7565164 | 0.015 SOL | +| Linea | 59144 | 0.001 ETH | +| Base | 8453 | 0.001 ETH | +| Optimism | 10 | 0.001 ETH | +| Neon | 245022934 | 0.75 NEON | +| Gnosis | 100 | 1 xDAI | +| Lightlink | 1890 | 0.0005 ETH | +| Metis | 1088 | 0.02 METIS | + +The fee is fully refunded in case the limit order is canceled. + +**Protocol fees can be changed. Hence, for any on-chain interactions with deBridge, fees must not be hardcoded but queried dynamically from the state of the DLN smart contract. Please refer to Estimating the order to learn how to query the actual flat fee from the smart contract.** diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/README.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/README.md new file mode 100644 index 00000000..55334782 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/README.md @@ -0,0 +1,2 @@ +# Interacting with smart contracts + diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/creating-calldata-for-solana.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/creating-calldata-for-solana.md new file mode 100644 index 00000000..51e64efc --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/creating-calldata-for-solana.md @@ -0,0 +1,138 @@ +# Creating Calldata for Solana + +### 1. Intro + +Solana calldata is a serialized `TransactionInstruction` list with additional metadata (see next sections). It can be serialized using a wasm module built by deBridge. + +### 2. Expenses + +Determine how much lamports your instruction spends on the destination network (most often, for account creation). Record this value as expenses. Each instruction is technically worth 5000 lamports (since we can't determine how many resources it will spend in advance, the implication is that it can be executed in a separate transaction). Therefore, 5000 + expenses is the estimate of how much lamports will cost the execution. + +### 2.1. Rewards + +Reward is an amount that covers taker expenses (expenses field) and makes execution of calldata profitable for executor => makes calldata to be executed automatically. Reward for each instruction is deducted from the wallet placeholder amount. **Rewards can't be native sol**. Rewards are set by the DLN API. + +### 3. Pubkey substituion + +Determine which accounts in the instruction are input-dependent and cannot be passed directly from the user for security reasons. + +For example, if there is a PDA in the destination network that depends on some unique transfer identifier, then we need to form \`PubkeySubstitutions\` + +### 3.1 Expenses + +As well as pubkey substitutions, placeholders could be used to substitute extcall accounts, but placeholders can't be used to calculate ATA during extcall execution. At the moment we have the following placeholders: + +* **Wallet Placeholder:** `J4vKrc4pCdtiHpxFDfBy4iyZ22Uf7fBjJyJ817k4673y` - if you set this pubkey to some account, it will be replaced by actual Submission Wallet during execution. Submission wallet is a [token account](https://github.com/solana-labs/solana-program-library/blob/523156a0cdd9cada27036bd72d326bc40c00f85f/token/program/src/state.rs#L83-L106) that contains transferred tokens during execution. +* **Submission Placehoder:** `7cu34CRu47UZKLRHjt9kFPhuoYyHCzAafGiGWz83GNFs` will be replaced by [Submission account](https://github.com/debridge-finance/debridge-solana-sdk/blob/5c3f5149504daddab38d5383ae6c8c15efb4235c/src/debridge\_accounts.rs#L59-L79) during execution. [Submission account](https://github.com/debridge-finance/debridge-solana-sdk/blob/5c3f5149504daddab38d5383ae6c8c15efb4235c/src/debridge\_accounts.rs#L59-L79) contains transfer metadata such as native sender, send from chain, etc. +* **Authority Placeholder:** `2iBUASRfDHgEkuZ91Lvos5NxwnmiryHrNbWBfEVqHRQZ` will be replaced by Submission Authority account during execution. Submission authority is an owner/authority account for Submission Wallet. It is this account that manages [#2.-expenses](https://docs.dln.trade/dln-on-chain/creating-calldata-for-solana#2.-expenses). + +If both placeholder and substitution are used for the same account, only substitution will be performed. + +### 4. DataSubstitution + +If you need a transfer amount as part of your transfer and it cannot be calculated in advance, then you must use `DataSubstitution`. One substitution is now available (`SubmissionAuthWalletAmount`) which works as follows. Takes the `account_index` account of the current instruction, interprets it as a token account, takes its balance, chooses its encoding (big endian, little endian), uses `substration` and inserts it into the current instruction by `offset` before calling it. + +### 5. Calldata serialization + +Instructions should be serialized one by one, final calldata is a concatenation of separately serialized instructions. + +Solana's `TransactionInstruction`s could be serialized into calldata format using `@debridge-finance/debridge-external-call` npm package: + +Copy + +```typescript +import * as wasm from "@debridge-finance/debridge-external-call"; +import { PublicKey, TransactionInstruction } from "@solana/web3.js"; + +/** + * Substitutes amount at offset with `walletBalance(accounts[account_index]) - subtraction` + */ +type AmountSubstitution = { + /** + * big or little endian + */ + is_big_endian: boolean; + /** + * At what offset substitution should be done + */ + offset: number; + /** + * index of account in TransactionInstruction.keys to get balance for + */ + account_index: number; + /** + * Amount to deduct from wallet balance + */ + subtraction: number; +}; + +/** + * Since we don't know submissionAuth at the moment of calldata preparation we can prepare substitution to replace + * account at `index` with actual ATA(submissionAuth, tokenMint) during execution + */ +type WalletSubstitution = { + /** + * Token mint to calculate ATA for + */ + token_mint: string; + /** + * Account at this index will be replaced with ATA(submissionAuth, tokenMint) during execution + */ + index: number; +}; + +/** + * Structure required by wasm module + */ +interface IExtIx { + keys: { + pubkey: string; + isSigner: boolean; + isWritable: boolean; + }[]; + data: Buffer; + programId: string; +} + +function ixToIExtIx(ix: TransactionInstruction): IExtIx { + return { + keys: ix.keys.map((meta) => ({ + pubkey: meta.pubkey.toBase58(), + isSigner: meta.isSigner, + isWritable: meta.isWritable, + })), + programId: ix.programId.toBase58(), + data: ix.data, + }; +} + +function serialize( + instruction: TransactionInstruction, + substitutions?: { + amountSubstitutions?: AmountSubstitution[]; + walletSubstitutions?: WalletSubstitution[]; + }, + expense?: bigint, + reward?: bigint, + isInMandatoryBlock: boolean = false, +) { + const ixWrapper = new wasm.ExternalInstructionWrapper( + reward, + expense, + isInMandatoryBlock, + substitutions?.amountSubstitutions ?? [], + substitutions?.walletSubstitutions ?? [], + ixToIExtIx(instruction), + ); + + return ixWrapper.serialize(); +} + +const ix1: TransactionInstruction; +const ix2: TransactionInstruction; + +const serializedIx1 = serialize(ix1, undefined, 1000n); +const serializedIx2 = serialize(ix2, undefined, 2000n); + +const calldata = Buffer.concat([serializedIx1, serializedIx2 /** rest serialized instructions if any */]); +``` diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/filling-orders.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/filling-orders.md new file mode 100644 index 00000000..7207cbc6 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/filling-orders.md @@ -0,0 +1,3 @@ +# Filling orders + +We are going to release a reference documentation for fulfilling orders placed on the deBridge Liquidity Network Protocol soon. Until this, please look at the documentation on [`dln-taker`](https://github.com/debridge-finance/dln-taker#dln-taker) — our open source service for solvers that automates order estimation and fulfillment. diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/introduction.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/introduction.md new file mode 100644 index 00000000..2d0251a7 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/introduction.md @@ -0,0 +1,9 @@ +# Introduction + +The deBridge Liquidity Network Protocol is an on-chain system of smart contracts where users place their cross-chain limit orders, giving a specific amount of input token on the source chain (`giveAmount` of the `giveToken` on the `giveChain`) and specifying the outcome they are willing to take on the destination chain (`takeAmount` of the `takeToken` on the `takeChain`). + +The given amount is being locked by the `DlnSource` smart contract on the source chain and anyone with enough liquidity (called _Solvers_) can attempt to fulfill the order by calling the `DlnDestination` smart contract on the destination chain supplying the requested amount of tokens the user is willing to take. After the order is fulfilled, the supplied amount is immediately transferred to the recipient specified by the user, and a cross-chain message is sent to the source chain via the deBridge infrastructure to unlock the funds, effectively completing the order.Getting ready to make on-chain calls + +The DLN Protocol consists of two contracts: the `DlnSource` contract responsible for order placement, and the `DlnDestination` contract responsible for order fulfillment. + +Currently, both contracts are deployed on the [supported blockchains](../fees-and-supported-chains.md) effectively allowing anyone to place orders in any direction. Contract addresses and ABIs can be found here: [Trusted Smart Contracts](../deployed-contracts.md) diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/placing-orders.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/placing-orders.md new file mode 100644 index 00000000..d2ce2256 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/placing-orders.md @@ -0,0 +1,226 @@ +# 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. + +{% hint style="info" %} +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. +{% endhint %} + +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 + +``` +25,000 * (10,000 - 8) / 10,000 - 6 = 24,974 DOGE + +(10,000 is a basis point denominator, see https://en.wikipedia.org/wiki/Basis_point) +``` + +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, + +1. set USDC token approval to allow the `DlnSource` contract spend tokens on your behalf, +2. call the `DlnSource.createOrder()` method: + +Copy + +``` +function createOrder( + OrderCreation calldata _orderCreation, + bytes calldata _affiliateFee, + uint32 _referralCode, + bytes calldata _permitEnvelope +) external payable returns (bytes32 orderId); +``` + +**Preparing an `OrderCreation` struct** + +`OrderCreation` has the following structure: + +``` +struct OrderCreation { + // the address of the ERC-20 token you are giving; + // use the zero address to indicate you are giving a native blockchain token (ether, matic, etc). + address giveTokenAddress; + + // the amount of tokens you are giving + uint256 giveAmount; + + // the address of the ERC-20 token you are willing to take on the destination chain + bytes takeTokenAddress; + + // the amount of tokens you are willing to take on the destination chain + uint256 takeAmount; + + // the ID of the chain where an order should be fulfilled. + // Use the list of supported chains mentioned above + uint256 takeChainId; + + // the address on the destination chain where the funds + // should be sent to upon order fulfillment + bytes receiverDst; + + // the address on the source (current) chain who is allowed to patch the order + // giving more input tokens and thus making the order more attractive to takers, just in case + address givePatchAuthoritySrc; + + // the address on the destination chain who is allowed to patch the order + // decreasing the take amount and thus making the order more attractive to takers, just in case + bytes orderAuthorityAddressDst; + + // an optional address restricting anyone in the open market from fulfilling + // this order but the given address. This can be useful if you are creating a order + // for a specific taker. By default, set to empty bytes array (0x) + bytes allowedTakerDst; // *optional + + // set to an empty bytes array (0x) + bytes externalCall; // N/A, *optional + + // an optional address on the source (current) chain where the given input tokens + // would be transferred to in case order cancellation is initiated by the orderAuthorityAddressDst + // on the destination chain. This property can be safely set to an empty bytes array (0x): + // in this case, tokens would be transferred to the arbitrary address specified + // by the orderAuthorityAddressDst upon order cancellation + bytes allowedCancelBeneficiarySrc; // *optional +} +``` + +**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](https://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 the `DlnSource` contract to spend tokens on your behalf. This argument accepts `amount` + `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`). + +``` +// preparing an order +OrderCreation memory orderCreation; +orderCreation.giveTokenAddress = 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48; // USDC +orderCreation.giveAmount = 25000000000; // 25,000 USDC +orderCreation.takeTokenAddress = abi.encodePacked(0xba2ae424d960c26247dd6c32edc70b295c744c43); +orderCreation.takeAmount = 2497400000000; // 249,740 DOGE +orderCreation.takeChainId = 56; // BNB Chain +orderCreation.receiverDst = abi.encodePacked(0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045); +orderCreation.givePatchAuthoritySrc = 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045; +orderCreation.orderAuthorityAddressDst = abi.encodePacked(0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045); +orderCreation.allowedTakerDst = ""; +orderCreation.externalCall = ""; +orderCreation.allowedCancelBeneficiarySrc = ""; + +// getting the protocol fee +uint protocolFee = DlnSource(dlnSourceAddress).globalFixedNativeFee(); + +// giving approval +IERC20(orderCreation.giveTokenAddress).approve(dlnSourceAddress, orderCreation.giveAmount); + +// placing an order +bytes32 orderId = DlnSource(dlnSourceAddress).createOrder{value: protocolFee}( + orderCreation, + "", + 0, + "" +); +``` + +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: + +``` +event CreatedOrder( + Order order, + bytes32 orderId, + bytes affiliateFee, + uint256 nativeFixFee, + uint256 percentFee, + uint32 referralCode +); +``` + +which contains an `Order` structure that is important to know to be able to fulfill or cancel this order. + +#### Tracking order status + +{% hint style="warning" %} +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). +{% endhint %} + +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: + +``` +function takeOrders(bytes32 orderId) + external + view + returns ( + uint8 status, + address takerAddress, + uint256 giveChainId + ); +``` + +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 request +* `status=3`: **cancel** procedure has been initiated to unlock the given funds on the source chain, as per order's `orderAuthorityAddressDst` request + +Alternatively, you can capture events emitted by the `DlnDestination` contact: + +``` +event FulfilledOrder(Order order, bytes32 orderId, address sender, address unlockAuthority); +event SentOrderCancel(Order order, bytes32 orderId, bytes cancelBeneficiary, bytes32 submissionId); +``` + +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](../../the-debridge-messaging-protocol/protocol-overview.md) 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: + +``` +function sendEvmOrderCancel( + Order memory _order, + address _cancelBeneficiary, + uint256 _executionFee +) external payable; +``` + +* 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](../../the-debridge-messaging-protocol/fees-and-supported-chains.md); +* for the `_order` argument, use the `Order` structure obtained from the `CreatedOrder()` 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 the `allowedCancelBeneficiarySrc` 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](https://explorer.debridge.finance/) and claim it manually. Consider understanding [how the cross-chain call is handled](../../the-debridge-messaging-protocol/development-guides/lifecycle-of-a-cross-chain-call.md). + +Finally, you are ready to initiate a cancellation procedure: + +``` +uint protocolFee = IDebridgeGate(DlnDestination(dlnDestinationAddress).deBridgeGate()) + .globalFixedNativeFee(); +uint executionFee = 30000000000000000; // e.g. 0.03 BNB ≈ $10 +DlnDestination(dlnDestinationAddress).sendEvmOrderCancel{value: protocolFee + executionFee}( + order, + 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045, + executionFee +); +``` diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/withdrawing-affiliate-fees.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/withdrawing-affiliate-fees.md new file mode 100644 index 00000000..ed90023d --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-smart-contracts/withdrawing-affiliate-fees.md @@ -0,0 +1,43 @@ +# Withdrawing Affiliate Fees + +The affiliate fee can be specified by anyone who integrates with the DLN API or uses the [deBridge Widget](https://app.debridge.finance/widget). The fee is received by the beneficiary at the moment when the solvers unlocks liquidity from the fulfilled order (usually a few hours after the order is fulfilled). + + + +**EVM chains** + +For orders initiated on EVM chains, the affiliate fee is transferred to the beneficiary address automatically in the same transaction where the solver unlocks liquidity from the fulfilled order. + +**Solana** + +For orders initiated from Solana, the affiliate fee is claimed by the beneficiary who should call the `withdrawAffiliateFee` method of the DLN program on Solana. Example snippet: + +```typescript +import { Solana } from "@debridge-finance/dln-client" +import { Connection, PublicKey, clusterApiUrl } from "@solana/web3.js"; + +function findAssociatedTokenAddress(wallet: PublicKey, tokenMint: PublicKey): [PublicKey, number] { + return PublicKey.findProgramAddressSync([wallet.toBytes(), new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA").toBytes(), tokenMint.toBytes()], new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")); +} + +const solanaClient = new Solana.DlnClient( + new Connection(clusterApiUrl("mainnet-beta")), // better use your own RPC + new PublicKey("src5qyZHqTqecJV4aY6Cb6zDZLMDzrDKKezs22MPHr4"), + new PublicKey("dst5MGcFPoBeREFAA5E3tU5ij8m5uVYwkzkSAbsLbNo"), + new PublicKey("DEbrdGj3HsRsAzx6uH4MKyREKxVAfBydijLUF3ygsFfh"), + new PublicKey("DeSetTwWhjZq6Pz9Kfdo1KoS5NqtsM6G8ERbX4SSCSft"), +) +type Order = { + orderId: string; + beneficiary: PublicKey; + giveToken: PublicKey; +} +// load order in expected format +const order: Order; +// order could also be loaded from chain by order creation tx hash +// const order = solanaClient.getOrderFromTransaction({ giveChain: ChainId.Solana, txHash: "create tx hash" }, {}); + +// build withdraw tx +const tx = await solanaClient.source.withdrawAffiliateFee(order.orderId, order.beneficiary, findAssociatedTokenAddress(order.beneficiary, order.giveToken)[0]); +// send withdraw tx +``` diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/README.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/README.md new file mode 100644 index 00000000..73672942 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/README.md @@ -0,0 +1,2 @@ +# Interacting with the API + diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/affiliate-fees.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/affiliate-fees.md new file mode 100644 index 00000000..59f87745 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/affiliate-fees.md @@ -0,0 +1,26 @@ +# Affiliate fees + +### Same-chain affiliate fees + +#### EVM single-chain affiliate fee + +To get affiliate fee when user performs single-chain swap on Solana chain `affiliteFeeBeneficiary` & `affiliateFeePercent` request params should be set. + +* Affiliate fee percent - percent of the **output amount** to receive as fee +* Affiliate fee beneficiary - evm address that will receive fee + +#### Solana single-chain affiliate fee + +To get affiliate fee when user performs single-chain swap on Solana chain `affiliteFeeBeneficiary` & `affiliateFeePercent` request params should be set. + +* Affiliate fee percent - percent of the **output amount** to receive as fee +* Affiliate fee beneficiary - Jupiter referral key, could be generated at [https://referral.jup.ag/dashboard](https://referral.jup.ag/dashboard) . Fees could be claimed at jupiter referral dashboard + +### Cross-chain affiliate fees + +Integrator could receive affiliate fee from order creation. `affiliteFeeBeneficiary` & `affiliateFeePercent` request params should be set. + +* Affiliate fee percent - percent of input order amount that will be sent to affiliate fee beneficiary on order completion +* Affiliate fee beneficiary - receiver of the affiliate fee. Pubkey for Solana, address for EVM + +Withdrawal details could be found [here](../interacting-with-smart-contracts/withdrawing-affiliate-fees.md) diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/cancelling-the-order.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/cancelling-the-order.md new file mode 100644 index 00000000..06a13c43 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/cancelling-the-order.md @@ -0,0 +1,32 @@ +# Cancelling the Order + +It can be the case that the given order remains unfulfilled for a prolonged period of time. The reason for this may be that the order became unprofitable, and no one is willing to fulfill it. In this case, the order must be cancelled to unlock the input amount of funds. + +The only way to cancel the order is to initiate the cancellation procedure it was intended to be fulfilled on (the `dstChainId` parameter). 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 DLN 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. + +The cancellation procedure can only be initiated by the `dstChainOrderAuthorityAddress` in a separate transaction on the destination chain. Such transaction can be requested by calling the `/v1.0/dln/order/:id/cancel-tx` endpoint: + +> `https://api.dln.trade/v1.0/dln/order/0x9ee6c3d0aa68a7504e619b02df7c71539d0ce10e27f593bf8604b62e51955a01/cancel-tx` + +This gives the response with the transaction data ready to be signed and broadcasted to the destination chain: + +``` +{ + "tx": { + "data": "0xd38d96260000000000000000000000000000000[...truncated...]", + "to": "0xe7351fd770a37282b91d153ee690b63579d6dd7f", + "value": "35957750149468810", + , + "chainId": 43114 + } +}, +``` + +Several considerations: + +* the transaction can be submitted only to the chain where the order has been intended to be fulfilled on +* the transaction call would be accepted only if made by the `dstChainOrderAuthorityAddress` specified during the given order creation +* the funds locked on the source chain upon order created are returned to the `srcChainOrderAuthorityAddress` specified during the given order creation +* the `value` for the transaction is always positive needed 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](https://docs.debridge.finance/build-with-debridge/getting-started#a-protocol-fee); + * a small amount to cover the gas on the source chain, which gives an incentive to keepers for the successful claim of the cross-chain message on the source chain. In other words, this is a prepayment for potential gas expenses, that will be transferred by the protocol. diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/getting-a-quote.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/getting-a-quote.md new file mode 100644 index 00000000..61ec15ee --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/getting-a-quote.md @@ -0,0 +1,79 @@ +# Getting a Quote + +{% hint style="info" %} +The [/quote](https://api.dln.trade/v1.0/#/DLN/DlnOrderControllerV10\_estimateTakeAmountOrder) endpoint of DNL API should be used only to display outcomes of the trades when the address of the user is unknown (e.g. to let the user see prices of cross-chain trades before one connects the wallet to the dApp). + +Whenever an address is known, make sure to call `/create-tx` directly. +{% endhint %} + +To place an order that would be reasonably profitable to incentivize a solver to fulfill it, a quote must not only reflect the current market exchange rate but also include relevant fees: the affiliate fee (in case you are going to collect an affiliate fee), the DLN protocol fee, the taker's margin fee; additionally, a quote must cover all implicit operating expenses incurred by a taker during and after order fulfillment (that includes Taker's gas costs for fulfillment and unlock of liquidity in the source chain). + +The `/v1.0/dln/order/quote` endpoint performs all necessary calculations to provide the best reasonable quote for the given input. + +Let's get a quote for our use-case by calling the `/v1.0/dln/order/quote` endpoint with the following parameter values: + +| Parameter | Value | Description | +| ------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `srcChainId` | `56` | specifies the ID of the BNB Chain as the chain where an order would be placed | +| `srcChainTokenIn` | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` | sets the input token (the user is willing to give) to the USDC token address on the BNB Chain | +| `srcChainTokenInAmount` | `100000000000000000000` | specifies the desired input amount: since the USDC token contract uses 18 decimals (_the number of digits that come after the decimal place when displaying token values on-screen_), the simple math: `100*10^18` leads to `100000000000000000000` as the value representing 100 USDC tokens | +| `dstChainId` | `43114` | specified the Avalanche network chain ID as the destination chain where an order should be fulfilled | +| `dstChainTokenOut` | 
0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7
+
| sets the output token (the user is willing to take) to the USDT token address on Avalanche | +| `prependOperatingExpense` | `true` | asks the API to add the approximate amount of operating expenses to the amount of input token before making a quote | +| `affiliateFeePercent` | `0.1` | asks the order to accrue the given share of input amount, which would be paid after an order gets fulfilled and unlocked | + +Calling the endpoint: + +> `https://api.dln.trade/v1.0/dln/order/quote?srcChainId=56&srcChainTokenIn=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d&srcChainTokenInAmount=100000000000000000000&dstChainId=43114&dstChainTokenOut=0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7&prependOperatingExpenses=true&affiliateFeePercent=0.1` + +gives a response with the recommended amount of input token, and several details describing how it has been calculated. The recommended amount of the output token (USDT in our case) available in the `estimation.dstChainTokenOut.recommendedAmount` property — this is the amount that can be suggested to a user for explicit approval before placing an order. + +At the time of writing, the response contains the following values: + +``` +{ + "estimation": { + "srcChainTokenIn": { + "address": "0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d", + "decimals": 18, + "name": "USD Coin", + "symbol": "USDC", + "chainId": 56, + , + , + "approximateOperatingExpense": "722632000000000000", + }, + "dstChainTokenOut": { + "address": "0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7", + "decimals": 6, + "name": "TetherToken", + "symbol": "USDt", + "chainId": 43114, + "amount": "99623050", + + }, + + [...] + }, + + [...], + + "tx": { + "allowanceTarget": "0xeF4fB24aD0916217251F553c0596F8Edc630EB66", + "allowanceValue": "100722632000000000000" + }, +} +``` + +This response states that executing an order to swap 100 USDC on BNB Chain to USDT on Avalanche requires approximately 0.722632 USDC, so this has been added to the input amount, resulting 100.722632 USDC to be charged from the user upon order creation. + +Additionally, 0.100722632 USDC is accrued as an affiliate fee upon order creation. + +{% hint style="info" %} +The affiliate fee is paid only after the order gets fulfilled, and after the taker has unlocked the order in the source chain. +{% endhint %} + +The most important part is the recommended amount of the output token: the API endpoint assumes that takers would be incentivized to fulfill an order with the given input at the time of the request if taking 99.623050 USDT. Not bad for a cross-chain swap/value transfer! + +If a user is comfortable with the quote, a transaction to create a limit order with the given quote can be requested. diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/quick-start-guide.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/quick-start-guide.md new file mode 100644 index 00000000..0e40df13 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/quick-start-guide.md @@ -0,0 +1,34 @@ +--- +description: >- + This document contains an overview of the deBridge Liquidity Network API + endpoints, giving readers an expedited understanding of how to get quotes, + place, track and manage limit orders. +--- + +# Quick Start Guide + +The DLN API provides developers an effortless way to interact with the DLN protocol and trade across chains in seconds with deep liquidity, limit orders, and protection against slippage and MEV. The API takes the burden off of building complex and sometimes painful interactions with blockchain RPCs and smart contracts by providing a complete set of RESTful endpoints, sufficient to quote, create, and manage trades during their whole lifecycle. + +{% hint style="info" %} +The **DLN API** with Swagger resides at [dln.debridge.finance](https://dln.debridge.finance) + +Additionally, a JSON representation of the API can be found here: [dln.debridge.finance/v1.0-json](https://dln.debridge.finance/v1.0-json) +{% endhint %} + +The lifecycle of an order is defined as follows: + +* getting a quote +* requesting a transaction that places (creates) the limit order on-chain +* submitting a transaction to the source chain +* tracking the status of the order on the destination chain +* (optional) requesting a transaction that cancels the limit order on the destination chain + +This guide gives a brief step-by-step overview of how to manage limit orders using DLN API endpoints. + +### A specific use case + +This article assumes a specific use case: a user, who has 100 [USDC on BNB Chain](https://bscscan.com/token/0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d), would like to receive a reasonable amount of [USDT on Avalanche](https://snowtrace.io/address/0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7). Additionally, an affiliate fee of 0.1% would be set during this order creation. + +{% hint style="info" %} +Hereinafter, we assume that the **input token** is USDC, and the user actually **gives 100 USDC;** the source chain is BNB Chain here. The **output token** is USDT, and the user is willing to **take** an amount of USDT recommended by the API. Here, the destination chain is Avalanche. +{% endhint %} diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/requesting-order-creation-transaction.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/requesting-order-creation-transaction.md new file mode 100644 index 00000000..0fde19e7 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/requesting-order-creation-transaction.md @@ -0,0 +1,74 @@ +# Requesting Order Creation Transaction + +Placing a trade on the deBridge Liquidity Network (DLN) actually means submitting a data struct to the DLN smart contract on the source chain. The data struct must represent the order, including but not limited to: the give and take offers, recipient, order authorities, and other variables. + +There is a [`/v1.0/dln/order/create-tx`](https://api.dln.trade/v1.0/#/DLN/DlnOrderControllerV10\_createOrder) endpoint for that, which takes all the parameters provided to the quote, the give and take parts of the quote, plus several more parameters describing the sender, recipient, and order authorities. + +To form the trade and get tx data to be signed, prepare the following parameters: + +| Parameter | Value | Description | +| ------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `srcChainTokenInAmount` | `100760488000000000000` | the input amount the user is willing to sell. Mind that this is a value modified by the quote endpoint and includes operating expenses. | +| `dstChainTokenOutAmount` | `99727937` | the recommended amount of output token. This value should be taken from quote response (see the `estimation.dstChainTokenOut.recommendedAmount` property) | +| `srcChainOrderAuthorityAddress` | `0x...` | the address (usually, a user wallet's address) on the source chain who is is authorised to patch the order and receive funds back during order cancellation | +| `dstChainTokenOutRecipient` | `0x...` | the address on the destination chain the `dstChainTokenOutAmount` of the output token should be transferred to upon successful order fulfillment | +| `dstChainOrderAuthorityAddress` | `0x...` | the address (usually, a user wallet's address) on the destination chain who is authorised to patch and cancel the order | +| `affiliateFeeRecipient` | `0x...` | the address on the source chain where the accrued affiliate fee would be transferred to after the order is being fulfilled and unlocked | + +Let's call the `/v1.0/dln/order/create-tx` endpoint with all these parameter values mentioned above: + +> `https://api.dln.trade/v1.0/dln/order/create-tx?srcChainId=56&srcChainTokenIn=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d&srcChainTokenInAmount=100722632000000000000&dstChainId=43114&dstChainTokenOut=0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7&dstChainTokenOutAmount=99623050&dstChainTokenOutRecipient=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&srcChainOrderAuthorityAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&dstChainOrderAuthorityAddress=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045&affiliateFeePercent=0.1&affiliateFeeRecipient=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` + +{% hint style="warning" %} +Keep in mind to set`srcChainOrderAuthorityAddress` and `dstChainOrderAuthorityAddress`to the addresses, a user has access to. Otherwise, the order has the risk of being stuck forever or the funds being sent to the wrong address during the [canceling procedure](broken-reference) (if that happens). +{% endhint %} + +The result of this request contains two objects. The `estimation` object which values can vary between different RPC requests, as the prices of crypto assets are highly volatile. It's important to check that the recommended amount hasn't changed much between the moment /create-tx was called to reflect the outcome of the trade to the user and the moment the user accepts the price and confirms the trade. + +If you specify `dstChainTokenOutAmount` instead of using `auto`, and have a goal to send a market order, it's important to ensure that the recommended amount of take token has not changed too much. E.g. the response below indicates that the recommended amount has decreased by 1.5 bps (0.015%), which is acceptable: + +{% hint style="info" %} +Having a large decrease in the recommended amount can indicate that the order won't be profitable and there won't be anyone willing to fulfill it. This would mean that a user would need to either wait indefinitely until the market conditions get better, or manually [cancel an order](cancelling-the-order.md) by submitting a separate transaction on the destination chain. +{% endhint %} + +{% hint style="warning" %} +**Important considerations** + +* It is advised to **expire the quote after 30 seconds** since it has been retrieved from the API +* It is advised to **expire the order creation transaction after 30 seconds** since it has been retrieved from the API +* For market orders, it is advised to refresh the quote if the recommended amount has changed significantly and use the recommended amount returned by /create-tx endpoint +{% endhint %} + + + +### EVM Chains + +The `tx` object has the following structure and is ready to be signed and broadcasted: + +``` +{ + "estimation": { ... } + + "tx": { + "data": "0xfbe16ca70000000000000000000000000000000[...truncated...]", + "to": "0xeF4fB24aD0916217251F553c0596F8Edc630EB66", + "value": "5000000000000000" + }, +} +``` + +If the refreshed estimation and the transaction look fine, it's time to submit a transaction to the source blockchain. + +#### Solana + +For DLN trades coming from Solana the `tx` object has only one field `data`: it's hex-encoded [VersionedTransaction](https://docs.solana.com/developing/versioned-transactions) + +``` +{ + "estimation": { ... } + + "tx": { + "data": "0x010000000000000000000000000000000000000[...truncated...]", + }, +} +``` diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/submitting-an-order-creation-transaction.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/submitting-an-order-creation-transaction.md new file mode 100644 index 00000000..f5633fea --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/submitting-an-order-creation-transaction.md @@ -0,0 +1,55 @@ +# Submitting an Order Creation Transaction + +After the transaction data has been retrieved from the API, it is ready to be submitted to the source blockchain: + +``` +{ + "estimation": { ... } + + "tx": { + "data": "0xfbe16ca70000000000000000000000000000000[...truncated...]", + "to": "0xeF4fB24aD0916217251F553c0596F8Edc630EB66", + "value": "5000000000000000" + }, +} +``` + +Field names from the `tx` object speak for themselves: + +* the `to` is the field the transaction should be sent to, and typically you should expect the address of one of the smart contracts responsible for forwarding; +* the `data` is the contents of the transaction, containing instructions related to swaps planned on the source or (and) on the destination chains, bridging settings, etc; +* the `value` is the amount of native blockchain currency that must be sent along with the transaction. + +However, there are a few things you must consider: + +First, the `value` is always positive, even if the input token is an ERC-20 token. This is because the underlying DLN protocol takes a fixed amount in the native currency, so the API always includes it as the transaction value. In the above example, the `value` equals the current fixed fee, which is 0.005 BNB on the BNB Chain. + +Second, in case the input token is an ERC-20 token, a user need to give approval to the smart contract address specified in the `tx.to` field prior to submitting this transaction so it can transfer them on the behalf of the sender. This can be typically done by calling either `approve()` or `increaseAllowance()` method of the smart contract which implements the token you are willing to swap. Approve at least the amount that has been specified as the `srcChainTokenInAmount` property during [`create-tx` endpoint call](broken-reference). + +Other than that, the transaction is ready to be signed by a user and broadcasted to the blockchain. It is also worth mentioning that the given transaction data can be used as a part of another transaction: a dApp can bypass the given `to`, `data` and `value` to your smart contract, and make a low-level call. There is even possible to create multiple transactions for different orders, and perform several low-level calls. + +{% hint style="info" %} +The affiliate fee is paid only after the order gets fulfilled, and the taker requests order unlock during the unlock procedure. +{% endhint %} + +#### Submit transaction in Solana + +For DLN trades coming from Solana the `tx` object returned by DLN API has only one field `data` which is hex-encoded [VersionedTransaction](https://docs.solana.com/developing/versioned-transactions) + +To convert the hex-encoded string into VersionedTransaction decode hex to buffer using any library and call VersionedTransaction.deserialize(decoded). + +Example: + +``` +import { VersionedTransaction, Connection, clusterApiUrl, Keypair } from "@solana/web3.js"; + +const wallet = new Keypair(); // your actual wallet here +const connection = new Connection(clusterApiUrl("mainnet-beta")); // your actual connection here +const tx = VersionedTransaction.deserialize(Buffer.from(tx.data.slice(2), "hex")); +const { blockhash } = await connection.getLatestBlockhash(); +tx.message.recentBlockhash = blockhash; // Update blockhash! +tx.sign([wallet]); // Sign the tx with wallet +connection.sendTransaction(tx); +``` + +More info about sending versioned transactions [here](https://docs.phantom.app/solana/sending-a-transaction-1#signing-and-sending-a-versioned-transaction). diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/tracking-a-status-of-the-order.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/tracking-a-status-of-the-order.md new file mode 100644 index 00000000..24d877d8 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-api/tracking-a-status-of-the-order.md @@ -0,0 +1,82 @@ +# Tracking a Status of the Order + +After the transaction has been [successfully included](broken-reference) in the source blockchain, it is time to retrieve the status of an order created within the given transaction. There are several ways to track the status of the trade. + +The first way is [`/filteredList`](https://stats-api.dln.trade/redoc/index.html?url=/swagger/v1/swagger.json#tag/Orders/operation/Orders\_GetOrders)[ ](https://stats-api.dln.trade/redoc/index.html?url=/swagger/v1/swagger.json#tag/Orders/operation/Orders\_GetOrders)method of dedicated `stats-api` that allows retrieving the history of all trades performed by the wallet and their statuses. Check [redoc](https://stats-api.dln.trade/redoc/index.html?url=/swagger/v1/swagger.json#tag/Orders/operation/Orders\_GetOrders) for more details. Stats-API Swagger is available at [this link](https://stats-api.dln.trade/swagger/index.html#/). + +Example of trade history for address `0xB779DaeAD6031Ef189cAD4Ac438c991Efe7635A7`: + +``` +curl -X 'POST' \ + 'https://stats-api.dln.trade/api/Orders/filteredList' \ + -H 'accept: application/json' \ + -H 'Content-Type: application/json' \ + -d '{ + "skip": 0, + "take": 20, + "creator":"0xB779DaeAD6031Ef189cAD4Ac438c991Efe7635A7" +}’ +``` + +To understand the data structure and how trade history can be reflected in your app, you can check the [DLN trade history](https://app.debridge.finance/orders) page of deExplorer which is using this endpoint to obtain data. + +In case detailed information on one specific trade is needed, [`/api/Orders/creationTxHash/`](https://dln-api.debridge.finance/swagger/index.html#/Orders/Orders\_GetOrderByCreationTx) endpoint of DLN API can be used. It returns the status and all the order parameters that are reflected on the order page of deExplorer. + +Example of how to retrieve DLN trade details based on orderID: [https://stats-api.dln.trade/api/Orders/creationTxHash/0x3fe11542154f53dcf3134eacb30ea5ca586c9e134c223e56bbe1893862469bc5](https://stats-api.dln.trade/api/Orders/creationTxHash/0x3fe11542154f53dcf3134eacb30ea5ca586c9e134c223e56bbe1893862469bc5) and [Link to the same order](https://app.debridge.finance/order?orderId=0x313d90a13e5f54efa3c065a98f1434c59d12ba9f4da8b224533bc56b6ed40d82) in deExplorer + +If multiple DLN orders were created in the same transaction, /creationTxHash will return information about the first one only + +{% hint style="info" %} +If multiple trades were created in a single transaction, there is an endpoint which returns the list of `orderId`s of the orders that were created by the given transaction: `/v1.0/dln/tx/:hash/order-ids`. +{% endhint %} + +Let's say, a transaction [`0x40ee524d5bb9c4ecd8e55d23c66c5465a3f137be7ae24df366c3fd06daf7de7e`](https://bscscan.com/tx/0x40ee524d5bb9c4ecd8e55d23c66c5465a3f137be7ae24df366c3fd06daf7de7e) has been submitted to the BNB Chain. Calling the endpoint: + +> [`https://stats-api.dln.trade/api/Transaction/0x40ee524d5bb9c4ecd8e55d23c66c5465a3f137be7ae24df366c3fd06daf7de7e/orderIds`](https://stats-api.dln.trade/api/Transaction/0x40ee524d5bb9c4ecd8e55d23c66c5465a3f137be7ae24df366c3fd06daf7de7e/orderIds) + +gives an array with only one `orderId` within it: + +``` +{ + "orderIds": [ + "0x9ee6c3d0aa68a7504e619b02df7c71539d0ce10e27f593bf8604b62e51955a01" + ] +} +``` + +{% hint style="info" %} +An array instead of a single `orderId` is returned because a top-level transaction may perform several calls to DLN, thus leading to multiple order creation. +{% endhint %} + +After the `orderId` has been revealed, it can be used to track the order's status by orderId specifically (instead of creation txHash). Use the `GET` [`/api/Orders/{orderId}`](https://stats-api.dln.trade/swagger/index.html#/Orders/Orders\_GetOrder) endpoint supplying the given `orderId`. Calling the endpoint: + +> [`https://stats-api.dln.trade/api/Orders/0x9ee6c3d0aa68a7504e619b02df7c71539d0ce10e27f593bf8604b62e51955a01`](https://stats-api.dln.trade/api/Orders/0x9ee6c3d0aa68a7504e619b02df7c71539d0ce10e27f593bf8604b62e51955a01) + +gives a status for the given order: + +``` +{ + "status": "ClaimedUnlock" +} +``` + +The order may have different statuses across its lifecycle, but the most important are `Fulfilled`, `SentUnlock` and `ClaimedUnlock` — all indicating that the order has been successfully fulfilled, and a recipient has received a precise amount of the output token. + +{% hint style="info" %} +If an order is in any of `Fulfilled`, `SentUnlock, or` `ClaimedUnlock` statuses, it can be displayed as fulfilled for the end-user. +{% endhint %} + +The affiliate fee (if set) that has been accrued during order creation is transferred to the `affiliateFeeRecipient` when the `ClaimedUnlock` status is reached. + +This is a complete set of all possible statuses that an order may have, according to the DLN API:\ + + +| Status | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Created` | The order has been placed on the DLN and is awaiting fulfillment. | +| `Fulfilled` | The order has been fulfilled. The take amount of the output token has been transferred to `dstChainTokenOutRecipient` | +| `SentUnlock` | An **unlock** procedure has been initiated by the taker (who fulfilled the order) on the destination chain to unlock the give amount of the input token on the source chain, as per taker request | +| `ClaimedUnlock` | An unlock procedure has been completed, effectively unlocking the input funds to the taker beneficiary, and the affiliate fee to the `affiliateFeeRecipient` on the source chain | +| `OrderCancelled` | A **cancel** procedure has been initiated by the `dstChainOrderAuthorityAddress` on the destination chain to unlock the given funds on the source chain, as per order's `srcChainRefundAddress` request | +| `SentOrderCancel` | A **cancel** procedure has been sent to the source chain to unlock the given funds on the source chain, as per order's `srcChainRefundAddress` request | +| `ClaimedOrderCancel` | A cancel procedure has been completed, effectively refunding locked funds to the `srcChainRefundAddress` on the source chain | diff --git a/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/README.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/README.md new file mode 100644 index 00000000..8abadf24 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/README.md @@ -0,0 +1,2 @@ +# Interacting with the deBridge App + diff --git a/docs/cross-chain-bridging-and-value-transfers/custom-linking.md b/docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/custom-linking.md similarity index 100% rename from docs/cross-chain-bridging-and-value-transfers/custom-linking.md rename to docs/dln-the-debridge-liquidity-network-protocol/interacting-with-the-debridge-app/custom-linking.md diff --git a/docs/dln-the-debridge-liquidity-network-protocol/introduction.md b/docs/dln-the-debridge-liquidity-network-protocol/introduction.md new file mode 100644 index 00000000..d4fd0b99 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/introduction.md @@ -0,0 +1,18 @@ +# Introduction + +**deBridge Liquidity Network** uses a 0-TVL cross-chain trading infrastructure to facilitate high-performance cross-chain exchange. Instead of using liquidity pools, the DLN executes all trades asynchronously through a self-organized liquidity network, providing developers and projects with the ability to leverage the fastest cross-chain experience on the market and transfer liquidity and information with faster time to finality than any legacy cross-chain solution. + +
+ +By shifting the cross-chain paradigm from bridging to networking, deBridge enables myriad unique features for applications and users: + +* Near-instant settlement +* Limit orders for any cross-chain trade +* Zero slippage on any order size +* Unlimited market depth +* Guaranteed rates and low fees +* Native token trading (no custodial risks of wrapped assets) +* Zero locked liquidity at risk (0-TVL) +* Rapidly scalable (can process any trading volume) +* Gasless limit orders (users can commit orders without any upfront costs — tokens are deducted only if execution is guaranteed on the destination chain) _(coming soon)_ +* Order + call data allows adding instructions to be executed together alongside order fulfillment diff --git a/docs/dln-the-debridge-liquidity-network-protocol/market-and-limit-orders.md b/docs/dln-the-debridge-liquidity-network-protocol/market-and-limit-orders.md new file mode 100644 index 00000000..d9821046 --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/market-and-limit-orders.md @@ -0,0 +1,28 @@ +# Market and Limit Orders + +The main trade-off of the deBridge Liquidity Network design is that order execution is not guaranteed in advance, just as it is not guaranteed by classical bridges based on liquidity pools, where a transaction may fail in the destination chain if slippage exceeds the slippage tolerance specified by the sender. + +With the deBridge Liquidity Network Protocol, a transaction can’t fail on the destination chain. An order is either fulfilled or not fulfilled, and if it’s not fulfilled, it means there is no taker willing to take the order. This may happen due to the following reasons: + +* The order doesn’t generate sufficient profit for a taker. In this case, it’s a limit order that will be fulfilled as soon as market conditions will make it profitable +* The order bears certain systemic risks. The advantage of the deBridge Liquidity Network Protocol is that it allows risks to be dynamically priced. Takers may not be willing to fulfill orders coming from chains where exploit or ecosystem-level hacks have happened. In this case, takers will expect a bigger premium laid into the spread of the order so that additional risks are compensated + +Users can place orders to exchange any assets at any price, but if the order premium covers all overhead costs for takers and brings them a profit, they are economically incentivized to fulfill the order as fast as possible. In this case, this is a market order that will be settled shortly. + +To facilitate the creation of market orders, deBridge provides a [Quick Start Guide](interacting-with-the-api/quick-start-guide.md). Any integrator or an app can query the API in order to retrieve the recommended price for the order for their users and secure its immediate execution. The quote recommended by the API lays in a spread that includes a 4bps incentive for takers and covers overhead costs such as gas. + +#### Joining the deBridge Liquidity Network Protocol as a Solver + +Solvers perform active on-chain liquidity management by fulfilling limit orders created through DLN. + +Check this Github Repository to learn more about how to get started as a Solver in DLN: [https://github.com/debridge-finance/dln-taker](https://github.com/debridge-finance/dln-taker) + +Solvers don't need to lock liquidity into pools, they always maintain ownership over their funds and have the sole ability to fulfill limit orders they deem profitable. + +#### Minimization of volatility risks for Solvers + +To minimize price fluctuation risks for takers, all transactions formed through DLN API automatically route any swap through the paired asset (USDC or ETH). For example, if the user wants to exchange a token (e.g. AAVE on Ethereum) for another volatile token (e.g. Matic on Polygon), then DLN API will form the transaction data where AAVE is pre-swapped into USDC, and a USDC->Matic DLN order is created in the same transaction. + +
+ +On the destination chain, solvers may hold USDC or ETH on a balance sheet of their on-chain addresses and swap their asset into the token requested in the order (e.g. MATIC), and fulfill it in the same transaction. When DlnDestination.sendUnlock() is called, the solver will receive the same paired asset (e.g. USDC) on the source chain, avoiding any price fluctuations of volatile assets. diff --git a/docs/dln-the-debridge-liquidity-network-protocol/protocol-overview.md b/docs/dln-the-debridge-liquidity-network-protocol/protocol-overview.md new file mode 100644 index 00000000..46c2d8ac --- /dev/null +++ b/docs/dln-the-debridge-liquidity-network-protocol/protocol-overview.md @@ -0,0 +1,51 @@ +# Protocol Overview + +deBridge uses a high-performance cross-chain trading infrastructure that consists of two layers: + +* Protocol layer: on-chain smart contracts +* Infrastructure layer: solvers who perform off-chain matching and on-chain settlement of trades + +The deBridge Liquidity Network Protocol is represented by a set of smart contracts that can be called by any on-chain address to create limit orders for cross-chain trades. When an order is created, the Maker provides a specific amount of an input token on the source chain and specifies the parameters of the order, such as the token address and the amount he accepts to receive in the destination chain. + +The given amount is then temporarily locked by the DLN smart contract on the source chain, and any on-chain address (named a **solver**) with sufficient liquidity in the destination chain can attempt to fulfill the order by calling the corresponding method of DLN smart contract and supplying the liquidity as requested by the maker in the DLN order parameters. After the order is fulfilled, a solver initiates a cross-chain message to be sent by the DLN smart contract to the source chain via the deBridge messaging protocol. When the message is delivered, it unlocks the funds on the source chain to the solver’s address, effectively completing the order. Below is a graphic outlining the process: + +
+ +Order Creation + +Specifically, there are two contracts deployed per supported chain: the `DlnSource` and the `DlnDestination` contracts. Whenever a maker decides to trade liquidity, it places an order by calling the `DlnSource.createOrder()` method on the source chain, providing the typed structure with precise requirements, specifically: the destination chain id, the address of a token, and the amount they expect to receive, the address of the receiver where the requested tokens should be sent to on the destination chain, and other system parameters. The smart contract assigns a unique identifier (hash) to the order, made of the values of its typed structure including the maker-specific determinants (address and nonce). The given amount of input token is taken from the user by the DlnSource contract and locked until the order is either unlocked or canceled, which can happen only through the DlnDestination smart contract on the destination chain. + +
+ +#### Order fulfillment + +Solvers perform off-chain tracking of all orders created through DlnSource smart contract, and whenever an order meets the solver's requirements (for example, the profitability, the margin, or even if the input token is whitelisted), they can attempt to fulfill the order by calling the `DlnDestination.fulfillOrder()` on the destination chain, supplying the amount of tokens requested in the order, and the typed structure representing the order placed on the source chain and order Id. At this point, no cross-chain communication is performed. The DlnDestination contract relies on the fact that the given order being placed on another chain can only be handled once on the destination chain, so it calculates the order identifier (hash) using the values from the given structure. It then checks that it matches the order Id passed by the solver and if the order status hasn’t been assigned as fulfilled or canceled. The smart contract processes the order by pulling the necessary amount of requested tokens from the solver and sending it to the receiver address, finally assigning ‘fulfilled status’ to the order. + +
+ +If the order generates some profit for the one who fulfills it, then solvers will have fair competition for its fulfillment. For example, an order to exchange 1000 USDC on BNB Chain for 990 USDC on Solana will bring 10 USDC profit to the solver that is the first to fulfill the order. Solvers are free to set their own requirements for transaction finality on the source chain. For example, solvers with an aggressive risk profile may decide to fulfill orders after one block confirmation and try to replay the maker’s transaction in case a reorg of the source chain happens after the order is fulfilled on the destination chain. + +#### Unlocking fulfilled orders + +The first solver that manages to change the status of the order in the DlnDestination smart contract to Fulfilled, gets the ability to call `DlnDestination.sendUnlock()`method which sends a cross-chain message through deBridge infrastructure to the DlnSource smart contract on the source chain. This message encodes a command to unlock funds initially locked for the given order identifier, and sends them to the address specified by the solver. + + + +
+ +When the DlnSource smart contract receives a message, before executing the command, it checks the identity of the message sender (address and chain id), to make sure it matches the identity of the DlnDestination smart contract stored in its state. + +If a maker decides to cancel their order, it must use a similar flow, and call the `DlnDestination.sendCancel()` method which will succeed only if the order is neither at the ‘fulfilled’ nor ‘canceled’ status. This method makes the smart contract send a cross-chain message to the DlnSource contract that encodes a command to unlock funds to the maker's address and change the order status to ‘canceled’. In this case, the DlnDestination contract on the destination chain acts as a source of trust for the propagation of the order status and sending corresponding commands. + +Note: In the lifecycle of an order, cross-chain communication (messaging) is only needed once the order has achieved its final status on the destination chain. This is so the DlnDestination smart contract can send a command to the DlnSource to unlock the order’s liquidity to the solver's address (in case of fulfillment) or to the maker address (in case of cancellation). When a cross-chain message is transferred through the deBridge infrastructure, strict finality requirements are applied before the message is signed by validators. The number of required block confirmations needed for each chain can be found [here](../the-debridge-messaging-protocol/fees-and-supported-chains.md). + +### Risk distribution + +Since the protocol doesn’t have any continuously locked liquidity, all DLN participants bear risks asynchronously. Makers bear the risk of cross-chain infrastructure only during the short time span from the moment an order has been created, until the moment when the order is fulfilled on the destination chain, which is typically an extremely short time period of seconds. + +Solvers bear risks only from the moment an order has been fulfilled, until the moment when the liquidity is unlocked on the source chain. These risks consist of two components: + +* The risk of order reversal due to source chain reorganization or fork. This risk is taken by solvers consciously, and is controlled by setting requirements for transaction finality: they fulfill orders only after the number of block confirmations in the source chain aligns with their risk profile. For example, a solver may execute small orders as soon as they appear on the source chain, but wait for extra block confirmations in the case of an exceptionally large order; more complex rules can be applied to meet the needs of solvers. This also creates the potential to compete for orders that are not yet broadcasted, fulfilling them even BEFORE they are included on the source blockchain, which is a win-win case: users get to receive the exact amount of funds they have requested quickly, and professional market makers take profits according to their risk profiles without affecting users. +* Risk of the cross-chain messaging infrastructure. The collusion of consensus participants is a trade-off that is born by all interoperability solutions without exception. The deBridge messaging infrastructure has a [delegated staking and slashing](../the-debridge-messaging-protocol/slashing-and-delegated-staking.md) module as part of the protocol design which prevents any theoretical collusion of validators. + +
diff --git a/docs/talks-and-videos.md b/docs/talks-and-videos.md index 622aa26b..4e4b31b4 100644 --- a/docs/talks-and-videos.md +++ b/docs/talks-and-videos.md @@ -2,7 +2,7 @@ #### **AMAs and Twitter Spaces** -
DateTitle
24-Jan-2023Beyond Bridges: A deep-dive into cross-chain interoperability
14-Dec-2022Partner Spotlight: Gasless anychain trading with ZeroSwap
17-Nov-2022Scaling DeFi for Mass Adoption with Sushi & Astrolab
8-Sep-2022Building Toward Web2 UX in Web3 with Unstoppable Domains
17-Aug-2022Building Towards a Secure Cross-Chain Future with David Schwed (Halborn) and Mudit Gupta (Polygon)
1-Jul-2022AMA with Magic Square
24-Jun-2022Going Cross-Chain with deBridge: Arbitrum
17-Jun-2022Going Cross-Chain with deBridge: Fantom
2-Dec-2021MiGoi - deBridge AMA session
17-Sep-2021Halborn AMA with Alex Smirnov of deBridge
+
DateTitle
15-May-2024deBridge: What is this dApp all about?
24-Jan-2023Beyond Bridges: A deep-dive into cross-chain interoperability
14-Dec-2022Partner Spotlight: Gasless anychain trading with ZeroSwap
17-Nov-2022Scaling DeFi for Mass Adoption with Sushi & Astrolab
8-Sep-2022Building Toward Web2 UX in Web3 with Unstoppable Domains
17-Aug-2022Building Towards a Secure Cross-Chain Future with David Schwed (Halborn) and Mudit Gupta (Polygon)
1-Jul-2022AMA with Magic Square
24-Jun-2022Going Cross-Chain with deBridge: Arbitrum
17-Jun-2022Going Cross-Chain with deBridge: Fantom
2-Dec-2021MiGoi - deBridge AMA session
17-Sep-2021Halborn AMA with Alex Smirnov of deBridge
diff --git a/docs/the-core-protocol/fees-and-supported-chains.md b/docs/the-core-protocol/fees-and-supported-chains.md deleted file mode 100644 index 1d044e52..00000000 --- a/docs/the-core-protocol/fees-and-supported-chains.md +++ /dev/null @@ -1,15 +0,0 @@ -# Fees and supported chains - -deBridge infrastructure takes a flat fee for each cross-chain message transfer, which users pay for decentralization and confidence since half of all fees will go as a reward to [deBridge validators](https://app.debridge.finance/validation-progress) who will be [financially liable](slashing-and-delegated-staking.md) for the proper operation of the protocol as liquid assets staked for them will act as protocol financial guarantees. - -The fee is paid in the blockchain's native (gas) token. For example, if the transfer is performed from the Ethereum chain, then the fixed ETH amount will be deducted from the user's wallet towards the protocol treasury on Ethereum. - -Fees paid for every sent message can be seen in [deBridge Explorer](https://app.debridge.finance/explorer) or retrieved from the state of the DebridgeGate smart contract (check [getting-started.md](../build-with-debridge/getting-started.md "mention")). - -{% hint style="warning" %} -deBridge flat fees can be changed by Governance. Hence, for any on-chain interactions with deBridge, fees **must not** be hardcoded but queried dynamically from the state of the DebridgeGate smart contract. -{% endhint %} - -### Current flat fee for messages sent from different chains - -
ChainChain IdMessage Transfer FeeBlocks finality
Arbitrum421610.001 ETH12
Avalanche431140.05 AVAX12
BNB Chain560.005 BNB12
Ethereum10.001 ETH12
Polygon1370.5 MATIC256
Fantom2504 FTM12
Solana75651640.03 SOLStatus Finalized
Linea591440.001 ETH12
Optimism100.001 ETH12
Base84530.001 ETH12
Neon2450229340.75 NEON32
Gnosis1001 xDAI12
Lightlink18900.0005 ETH12
Metis10880.02 METIS12
diff --git a/docs/the-core-protocol/transfers.md b/docs/the-core-protocol/transfers.md index 5c0ecc95..9ec4d086 100644 --- a/docs/the-core-protocol/transfers.md +++ b/docs/the-core-protocol/transfers.md @@ -1,8 +1,8 @@ # Transfers Flow -![](../.gitbook/assets/B.png) +
-## Transfers From Native Chain +## Transfers From Native (Source) Chain Let's consider the situation where the user or smart contracts performs a transfer of the asset and data from chain A to chain B. Then the following steps are performed: @@ -35,15 +35,15 @@ submissionId = keccak256( `debridgeID` is a hash of concatenation of the token native chain Id and native token address. * deBridge validation nodes track events emitted by `deBridgeGate` smart contract and after a minimum number of blocks confirmations validators submit the transfer identifier (submissionId) to the `deBridgeAggregator` contract on the target chain. `submissionId` is calculated as a hash of concatenation: -* The user or any arbitrary wallet (e.g. Keeper service) can call `claim` method of `deBridgeGate` by passing all transaction parameters and all validators' signatures. Smart contract will restore `submissionId` based on the set of passed parameters and if the minimum required number of validators' signatures is valid, the transaction is treated by protocol as valid and the asset is minted/unlocked to the receiver address and data is executed through the callProxy. +* The user or any arbitrary wallet (e.g. Keeper service) can call `claim` method of `deBridgeGate` by passing all transaction parameters and all validators' signatures. Smart contract will restore `submissionId` based on the set of passed parameters and if the minimum required number of validators' signatures is valid, the transaction is treated by the protocol as valid and the asset is minted/unlocked to the receiver address and data is executed through the callProxy. -deBridge protocol supports **multi-chain routing** when users can transfer deAssets between secondary chains directly, without the need to route them through the native chain. These transfers work in the same way, but deAsset is burnt in the chain where the transfer is originated and the corresponding amount of deAsset is minted in the target chain +deBridge protocol supports **multi-chain routing** when users can transfer deAssets between secondary chains directly, without the need to route them through the native chain. These transfers work in the same way, but deAsset is burnt in the chain where the transfer is originated and the corresponding amount of deAsset is minted on the target chain. ## Cross-Chain Transfers Execution Time Cross-chain transfer through deBridge normally takes a few minutes and the delay is caused by two factors: -1. The finality of the transaction in the blockchain where the transfer is originated -2. Time required for claim transaction to get into the block in the destination chain +1. The finality of the transaction on the blockchain where the transfer is originated +2. Time required for claim transaction to get into the block on the destination chain -Each blockchain has a different block generation time and requires a different number of block confirmations for ensured transaction finality, thus before validating the transaction validators must wait for its finality +Each blockchain has a different block generation time and requires a different number of block confirmations for ensured transaction finality, thus before validating the transaction validators must wait for its finality. diff --git a/docs/contracts/mainnet-addresses.md b/docs/the-debridge-messaging-protocol/deployed-contracts.md similarity index 99% rename from docs/contracts/mainnet-addresses.md rename to docs/the-debridge-messaging-protocol/deployed-contracts.md index e52d494b..1ab6be4e 100644 --- a/docs/contracts/mainnet-addresses.md +++ b/docs/the-debridge-messaging-protocol/deployed-contracts.md @@ -4,7 +4,7 @@ description: >- blockchains --- -# 📑 Mainnet Addresses +# 🟢 Deployed Contracts ### deBridge IaaS @@ -13,7 +13,7 @@ description: >- Proxy:\ [0x2328Ee20fA271073328DC94e52Dd5b61aa0C91A7](https://etherscan.io/address/0x2328Ee20fA271073328DC94e52Dd5b61aa0C91A7)\ Implementation:\ -[0xf46b9e22a2a5B07bd2F601d9A59b4E01424f5E35](../the-core-protocol/protocol-overview.md) +[0xf46b9e22a2a5B07bd2F601d9A59b4E01424f5E35](protocol-overview.md) ### Solana diff --git a/docs/the-debridge-messaging-protocol/development-guides/README.md b/docs/the-debridge-messaging-protocol/development-guides/README.md new file mode 100644 index 00000000..ffa812d5 --- /dev/null +++ b/docs/the-debridge-messaging-protocol/development-guides/README.md @@ -0,0 +1,2 @@ +# Development Guides + diff --git a/docs/build-with-debridge/getting-started.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/README.md similarity index 95% rename from docs/build-with-debridge/getting-started.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/README.md index a7718920..6628db7d 100644 --- a/docs/build-with-debridge/getting-started.md +++ b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/README.md @@ -1,8 +1,9 @@ -# Getting started +# Building an EVM-based dApp -**deBridge** is a secure interoperability layer for Web3 that enables arbitrary complex cross-chain interactions in a single transaction. Due to the ability to simultaneously send messages and value deBridge acts as a unified framework for all cross-chain needs and is capable of interconnecting any smart contract on any blockchain. +**deBridge is DeFi's internet of liquidity**, enabling any amount of cross-chain interactions (bridging, value transfers, ext calls, etc) in a single transaction. Due to the ability to simultaneously send messages and value deBridge acts as a unified framework for all cross-chain needs and is capable of interconnecting any smart contract on any supported blockchain.\ -![Cross-chain smart contract calls through deBridge](<../.gitbook/assets/image (1).png>) + +
This guide is a great starting point that covers all necessary topics to get you started building cross-chain interactions on top of the deBridge protocol and its' infrastructure. @@ -10,7 +11,9 @@ This guide is a great starting point that covers all necessary topics to get you Let's consider the following idea of the conceptual dApp consisting of two smart contacts: a `Counter` smart contract residing in one chain, where the integer property (`counter`) is stored and can be incremented by a call initiated by **and only by** the `Incrementor` contract from another chain. In other words, when we perform some action against the `Incrementor` contract, it initiates a cross-chain transaction (a submission, in terms of the deBridge protocol) which is being started on one chain, relayed to, and then executed on another chain; during this cross-chain transaction, a `Counter` contract is called. The following image presents a high-level overview of a cross-chain transaction we are going to achieve: -![A high level schema of the conceptual dApp](../.gitbook/assets/01.png) + + +
This document will guide you through building contracts, scripts and unit tests necessary to make this project happen. A self-contained source code of this dApp can be found on Github: [`debridge-finance/debridge-cross-chain-dapp-example.git`](https://github.com/debridge-finance/debridge-cross-chain-dapp-example). @@ -195,7 +198,7 @@ The gate accepts a variety of parameters through the `SubmissionAutoParamsTo` st * `PROXY_WITH_SENDER` tells the `CallProxy` to expose the address that initiated the cross-chain transaction (submission) on the origin chain. Again, choose wisely: as for our case, the `Counter` contract expects this data, so we need to ensure it's presented on the destination chain. {% hint style="info" %} -`A complete list of flags with their description can be found on` [smart-contract-interface.md](smart-contract-interface.md "mention") page +`A complete list of flags with their description can be found on` [evm-smart-contract-interfaces](evm-smart-contract-interfaces/ "mention") page {% endhint %} `fallbackAddress` is the address on the destination chain where the bridged funds will be transferred to in case the call to the receiver address fails AND `REVERT_IF_EXTERNAL_FAIL` is not set. Since we don't bridge any funds (only the calldata), this field is not very important though it is mandatory to set it. Mind that this address must be packed into bytes. @@ -278,7 +281,7 @@ Of course, this call may be crafted on-chain in your own contract or off-chain. ### Accompanying and finishing a submission {% hint style="info" %} -Consider reading the [lifecycle-of-a-cross-chain-call.md](lifecycle-of-a-cross-chain-call.md "mention") to get yourself familiar with how the cross-chain calls are handled. +Consider reading the [lifecycle-of-a-cross-chain-call.md](../lifecycle-of-a-cross-chain-call.md "mention") to get yourself familiar with how the cross-chain calls are handled. {% endhint %} After our smart contract (`Incrementor` in our case) submits a new cross-chain call, the `deBridgeGate` contract emits a `Sent` event containing all necessary details about the cross-chain call, including the `submissionId` — the global cross-chain identifier of such a call. The `submissionId` is the important thing to identify our submission, so we must capture it either by parsing the event manually or using [deBridge SDK (deSDK)](https://github.com/debridge-finance/desdk) which does [this action](https://github.com/debridge-finance/desdk#tracking-submissions) for us: @@ -307,7 +310,7 @@ The submission gets accepted by the validators after a transaction (containing t const isConfirmed = await submission.hasRequiredBlockConfirmations(); ``` -The number of block confirmations required for sent messages can be found in [fees-and-supported-chains.md](../the-core-protocol/fees-and-supported-chains.md "mention") section +The number of block confirmations required for sent messages can be found in [fees-and-supported-chains.md](../../fees-and-supported-chains.md "mention") section #### Pulling signatures @@ -352,7 +355,7 @@ Keep in mind that estimating gas for such transaction may have undesirable pitfa {% embed url="https://www.youtube.com/watch?v=Ke09y0VXtT0" %} * debridge protocol: advanced topics: - * [gathering-data-for-the-claim.md](advanced-topics/gathering-data-for-the-claim.md "mention") + * [gathering-data-for-the-claim.md](../gathering-data-for-the-claim.md "mention") * deBridge protocol flags explained (coming soon) * Transaction bundling explained (coming soon) * Execution fee explained (coming soon) diff --git a/docs/build-with-debridge/smart-contract-interface.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/README.md similarity index 93% rename from docs/build-with-debridge/smart-contract-interface.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/README.md index 106358df..9f6cf9bb 100644 --- a/docs/build-with-debridge/smart-contract-interface.md +++ b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/README.md @@ -1,4 +1,4 @@ -# Smart contract interface +# EVM smart contract interfaces Interaction with the deBridge infrastructure is as simple as calling the `send` method of `debridgeGate` smart-contract deployed on all supported blockchains. The method can be called by any arbitrary address — either EOA or smart contracts. @@ -25,7 +25,7 @@ If you integrate with or build applications on top of the deBridge infrastructur ### AutoParams structure -`_autoParams` is a structure that allows passing arbitrary messages and call data to be executed as an external call to the receiver address in the destination chain. This structure also enables setting an executionFee, a reward suggested to any wallet or keeper that will complete the transaction on the target chain. It enables a crypto-economic design where gas fees are paid from the blockchain where the transaction is initiated. The `_autoParams` field has the following structure: +`_autoParams` is a structure that allows passing arbitrary messages and call data to be executed as an external call to the receiver address on the destination chain. This structure also enables setting an executionFee, a reward suggested to any wallet or keeper that will complete the transaction on the target (destination) chain. It enables a crypto-economic design where gas fees are paid from the blockchain where the transaction is initiated. The `_autoParams` field has the following structure: ```solidity struct SubmissionAutoParamsTo { @@ -63,7 +63,7 @@ library Flags { `PROXY_WITH_SENDER` should be set whenever the receiving smart contract should check whether the message sender is trusted or not. If the flag was set during the claim transaction on the destination chain, the deBridge protocol will automatically store the submissionNativeSender address and submissionChainIdFrom, so that the receiving smart contract can read the properties and validate if the sender is trusted. -![](<../.gitbook/assets/Scheme 2.png>) +
The receiving smart contract should retrieve the address of callProxy from the debridgeGate smart contract. You can use [onlyControllingAddress](https://github.com/debridge-finance/debridge-contracts-v1/blob/main/contracts/examples/BridgeAppBase.sol#L62) modifier or inherit it from [BridgeAppBase.sol ](https://github.com/debridge-finance/debridge-contracts-v1/blob/main/contracts/examples/BridgeAppBase.sol)to properly implement this validation logic. diff --git a/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/README.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/README.md new file mode 100644 index 00000000..786ebd5d --- /dev/null +++ b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/README.md @@ -0,0 +1,9 @@ +# Interfaces + +* [ICallProxy](icallproxy.md) +* [IDeBridgeGate](idebridgegate.md) +* [IDeBridgeToken](idebridgetoken.md) +* [IDeBridgeTokenDeployer](idebridgetokendeployer.md) +* [IOraclesManager](ioraclesmanager.md) +* [ISignatureVerifier](isignatureverifier.md) +* [IWethGate](iwethgate.md) diff --git a/docs/contracts/interfaces/ICallProxy.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/icallproxy.md similarity index 100% rename from docs/contracts/interfaces/ICallProxy.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/icallproxy.md diff --git a/docs/contracts/interfaces/IDeBridgeGate.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgegate.md similarity index 100% rename from docs/contracts/interfaces/IDeBridgeGate.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgegate.md diff --git a/docs/contracts/interfaces/IDeBridgeToken.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgetoken.md similarity index 100% rename from docs/contracts/interfaces/IDeBridgeToken.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgetoken.md diff --git a/docs/contracts/interfaces/IDeBridgeTokenDeployer.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgetokendeployer.md similarity index 100% rename from docs/contracts/interfaces/IDeBridgeTokenDeployer.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/idebridgetokendeployer.md diff --git a/docs/contracts/interfaces/IOraclesManager.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/ioraclesmanager.md similarity index 100% rename from docs/contracts/interfaces/IOraclesManager.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/ioraclesmanager.md diff --git a/docs/contracts/interfaces/ISignatureVerifier.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/isignatureverifier.md similarity index 100% rename from docs/contracts/interfaces/ISignatureVerifier.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/isignatureverifier.md diff --git a/docs/contracts/interfaces/IWethGate.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/iwethgate.md similarity index 100% rename from docs/contracts/interfaces/IWethGate.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/interfaces/iwethgate.md diff --git a/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/libraries/README.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/libraries/README.md new file mode 100644 index 00000000..02741eda --- /dev/null +++ b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/libraries/README.md @@ -0,0 +1,3 @@ +# Libraries + +* [Flags](flags.md) diff --git a/docs/contracts/libraries/Flags.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/libraries/flags.md similarity index 100% rename from docs/contracts/libraries/Flags.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/libraries/flags.md diff --git a/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/README.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/README.md new file mode 100644 index 00000000..89b06ffd --- /dev/null +++ b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/README.md @@ -0,0 +1,6 @@ +# Periphery + +* [CallProxy](callproxy.md) +* [DeBridgeToken](debridgetoken.md) +* [DeBridgeTokenProxy](debridgetokenproxy.md) +* [SimpleFeeProxy](simplefeeproxy.md) diff --git a/docs/contracts/periphery/CallProxy.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/callproxy.md similarity index 100% rename from docs/contracts/periphery/CallProxy.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/callproxy.md diff --git a/docs/contracts/periphery/DeBridgeToken.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/debridgetoken.md similarity index 100% rename from docs/contracts/periphery/DeBridgeToken.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/debridgetoken.md diff --git a/docs/contracts/periphery/DeBridgeTokenProxy.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/debridgetokenproxy.md similarity index 100% rename from docs/contracts/periphery/DeBridgeTokenProxy.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/debridgetokenproxy.md diff --git a/docs/contracts/periphery/SimpleFeeProxy.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/simplefeeproxy.md similarity index 100% rename from docs/contracts/periphery/SimpleFeeProxy.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/periphery/simplefeeproxy.md diff --git a/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/README.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/README.md new file mode 100644 index 00000000..cea443ae --- /dev/null +++ b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/README.md @@ -0,0 +1,7 @@ +# Transfers + +* [DeBridgeGate](debridgegate.md) +* [DeBridgeTokenDeployer](debridgetokendeployer.md) +* [OraclesManager](oraclesmanager.md) +* [SignatureVerifier](signatureverifier.md) +* [WethGate](wethgate.md) diff --git a/docs/contracts/transfers/DeBridgeGate.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/debridgegate.md similarity index 100% rename from docs/contracts/transfers/DeBridgeGate.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/debridgegate.md diff --git a/docs/contracts/transfers/DeBridgeTokenDeployer.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/debridgetokendeployer.md similarity index 100% rename from docs/contracts/transfers/DeBridgeTokenDeployer.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/debridgetokendeployer.md diff --git a/docs/contracts/transfers/OraclesManager.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/oraclesmanager.md similarity index 100% rename from docs/contracts/transfers/OraclesManager.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/oraclesmanager.md diff --git a/docs/contracts/transfers/SignatureVerifier.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/signatureverifier.md similarity index 100% rename from docs/contracts/transfers/SignatureVerifier.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/signatureverifier.md diff --git a/docs/contracts/transfers/WethGate.md b/docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/wethgate.md similarity index 100% rename from docs/contracts/transfers/WethGate.md rename to docs/the-debridge-messaging-protocol/development-guides/building-an-evm-based-dapp/evm-smart-contract-interfaces/transfers/wethgate.md diff --git a/docs/build-with-debridge/advanced-topics/gathering-data-for-the-claim.md b/docs/the-debridge-messaging-protocol/development-guides/gathering-data-for-the-claim.md similarity index 100% rename from docs/build-with-debridge/advanced-topics/gathering-data-for-the-claim.md rename to docs/the-debridge-messaging-protocol/development-guides/gathering-data-for-the-claim.md diff --git a/docs/build-with-debridge/lifecycle-of-a-cross-chain-call.md b/docs/the-debridge-messaging-protocol/development-guides/lifecycle-of-a-cross-chain-call.md similarity index 87% rename from docs/build-with-debridge/lifecycle-of-a-cross-chain-call.md rename to docs/the-debridge-messaging-protocol/development-guides/lifecycle-of-a-cross-chain-call.md index 262411f3..0522181b 100644 --- a/docs/build-with-debridge/lifecycle-of-a-cross-chain-call.md +++ b/docs/the-debridge-messaging-protocol/development-guides/lifecycle-of-a-cross-chain-call.md @@ -4,9 +4,9 @@ Blockchains by their nature are siloed environments that cannot directly communi The following scheme visualizes a normal cycle of a typical cross-chain call, as it may look for the [conceptual cross-chain dApp](https://github.com/debridge-finance/debridge-cross-chain-dapp-example) where Incrementor is used as an example of the smart contract that sends a cross-chain message: -

Lifecycle of a cross-chain message transfer

+
-When a call to the `deBridgeGate.send()` method is made on the origin chain, the gate contract validates the input (its args and the `autoParams` struct), and if everything is correct (the data is unambiguous, the input asset covers the fees, etc), a special `Sent` event is emitted. This event exposes the following details of the submission: +When a call to the `deBridgeGate.send()` method is made on the origin (source) chain, the gate contract validates the input (its args and the `autoParams` struct), and if everything is correct (the data is unambiguous, the input asset covers the fees, etc), a special `Sent` event is emitted. This event exposes the following details of the submission: * `submissionId`, the identifier of the cross-chain transaction you've initiated; * `debridgeId`, the cross-chain identifier of the input asset, needed to correctly handle tokens across supported chains; @@ -16,12 +16,12 @@ You are advised to monitor this event to ensure your submission has been accepte [deBridge validators](https://app.debridge.finance/validation-progress) listen for these events emitted by the `deBridgeGate` smart contract deployed on all supported chains, and for each tracked event validator performs the following set of actions: -* waits a specific amount of block confirmations (12 block confirmations for supported EVM chains, and 256 block confirmations for Polygon network) to ensure the finality of the transaction where the event has been emitted, +* waits a specific amount of block confirmations (12 block confirmations for supported EVM chains, and 256 block confirmations for the Polygon network) to ensure the finality of the transaction where the event has been emitted, * validates the args and the structure, * if the data is correct, sign the message with its own private key, and publish the signature to Arweave. {% hint style="info" %} -Note: Validators' financial responsibility to be enabled through[slashing-and-delegated-staking.md](../the-core-protocol/slashing-and-delegated-staking.md "mention"). +Note: Validators' financial responsibility to be enabled through[slashing-and-delegated-staking.md](../slashing-and-delegated-staking.md "mention"). {% endhint %} After the minimum required number of validators have signed the message (eight at the time of writing, ⅔ of all possible signatures), the submission is confirmed and may be claimed on the destination chain. @@ -40,7 +40,7 @@ There are three ways to trigger a claiming txn: * manually, by visiting [deExplorer](https://explorer.debridge.finance/), where you can find your cross-chain transaction by its `submissionId` or even by the hash of the origin transaction, then sign the prepared claiming transaction using the browser wallet (MetaMask, etc); -![](<../.gitbook/assets/Screenshot 2022-07-20 at 20.01.38.png>) +
* automatically, by specifying sufficient `executionFee` property within your submission: in this case, Claimers will execute the transaction and deliver the message in case the supplied on the source chain `executionFee` (included gas) covers their gas on the destination chain. \ \ diff --git a/docs/build-with-debridge/getting-started-with-solana/README.md b/docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/README.md similarity index 97% rename from docs/build-with-debridge/getting-started-with-solana/README.md rename to docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/README.md index 59fad0de..fff119b2 100644 --- a/docs/build-with-debridge/getting-started-with-solana/README.md +++ b/docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/README.md @@ -2,9 +2,9 @@ description: How to interact with deBridge infrastructure from Solana --- -# Getting started with Solana +# Sending cross-chain messages from Solana -To streamline communication with deBridge programs on the Solana blockchain, the [debridge-solana-sdk](https://github.com/debridge-finance/debridge-solana-sdk) has been developed. This [Rust](https://github.com/rust-lang/rust) SDK allows for easy and efficient connection to the deBridge infrastructure, which enables decentralized transfers of messages and value between different blockchains. +To streamline communication with deBridge programs on the Solana blockchain, the [debridge-solana-sdk](https://github.com/debridge-finance/debridge-solana-sdk) has been developed. This [Rust](https://github.com/rust-lang/rust) SDK allows for easy and efficient connection to the deBridge infrastructure, which enables decentralized transfers of messages and value between different supported blockchains. To start using our sdk, add it to dependencies by [cargo](https://github.com/rust-lang/cargo): diff --git a/docs/build-with-debridge/getting-started-with-solana/off-chain-external-call-preparation-for-solana.md b/docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/off-chain-external-call-preparation-for-solana.md similarity index 100% rename from docs/build-with-debridge/getting-started-with-solana/off-chain-external-call-preparation-for-solana.md rename to docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/off-chain-external-call-preparation-for-solana.md diff --git a/docs/build-with-debridge/getting-started-with-solana/on-chain-external-call-preparation-for-solana.md b/docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/on-chain-external-call-preparation-for-solana.md similarity index 99% rename from docs/build-with-debridge/getting-started-with-solana/on-chain-external-call-preparation-for-solana.md rename to docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/on-chain-external-call-preparation-for-solana.md index dc1720b1..3cd7a365 100644 --- a/docs/build-with-debridge/getting-started-with-solana/on-chain-external-call-preparation-for-solana.md +++ b/docs/the-debridge-messaging-protocol/development-guides/sending-cross-chain-messages-from-solana/on-chain-external-call-preparation-for-solana.md @@ -1,6 +1,6 @@ # On-Chain external call preparation for Solana -Preparing an extcall to call programs in Solana is simple: +Preparing an extcall to call programs on Solana is simple: ## 1. Instruction diff --git a/docs/build-with-debridge.md b/docs/the-debridge-messaging-protocol/development-tools.md similarity index 58% rename from docs/build-with-debridge.md rename to docs/the-debridge-messaging-protocol/development-tools.md index 4b5db16b..2e9853a7 100644 --- a/docs/build-with-debridge.md +++ b/docs/the-debridge-messaging-protocol/development-tools.md @@ -2,14 +2,14 @@ description: Get started building cross-chain applications --- -# Development tools +# Development Tools -Explore [deBridge Developer Portal](https://debridge.finance/develop) to get started building secure and efficient cross-chain applications +Explore our [deBridge Developer Portal](https://debridge.finance/develop) to get started building secure and efficient cross-chain applications. ### Development tools -* [DLN API](https://docs.dln.trade/dln-api/quick-start-guide) is a is a high-performance cross-chain trading infrastructure built on deBridge with a unique 0-TVL design (no risks of locked liquidity). -* [deSwap widget](https://app.debridge.finance/widget) — offer seamless cross-chain swaps in any application with our customizable widget +* DLN API: is a high-performance cross-chain trading infrastructure built with deBridge with a unique 0-TVL design (no risks of locked liquidity). +* [deBridge widget](https://app.debridge.finance/widget): offer seamless and secure bridging and cross-chain value transfers in any application with our customizable widget. * [`debridge-hardhat`](https://github.com/debridge-finance/hardhat-debridge) is a plugin for Hardhat that provides the toolkit for creating a lightweight and blazing-fast emulation environment, behaving close to how the mainnet setup of the deBridge infrastructure does. * [deSDK](https://github.com/debridge-finance/desdk) is a library to send, track, and claim submissions programmatically. * [Solana transaction parser](https://github.com/debridge-finance/solana-tx-parser-public) is a powerful tool developed by the deBridge team to parse Solana transactions and analyze them in a human-readable format. diff --git a/docs/the-debridge-messaging-protocol/fees-and-supported-chains.md b/docs/the-debridge-messaging-protocol/fees-and-supported-chains.md new file mode 100644 index 00000000..91f189ea --- /dev/null +++ b/docs/the-debridge-messaging-protocol/fees-and-supported-chains.md @@ -0,0 +1,31 @@ +# Fees and Supported Chains + +deBridge takes a flat fee for each cross-chain message transfer, which users pay for decentralization and confidence since half of all fees will go as a reward to [deBridge validators](https://app.debridge.finance/validation-progress) who will be [financially liable](https://docs.debridge.finance/the-core-protocol/slashing-and-delegated-staking) for the proper operation of the protocol as liquid assets staked for them will act as protocol financial guarantees. + +The fee is paid in the blockchain's native (gas) token. For example, if the transfer is performed from the Ethereum chain, then the fixed ETH amount will be deducted from the user's wallet towards the protocol treasury on Ethereum. + +Fees paid for every sent message can be seen in [deBridge Explorer](https://app.debridge.finance/explorer) or retrieved from the state of the DebridgeGate smart contract (check [Getting started](https://docs.debridge.finance/build-with-debridge/getting-started)). + +{% hint style="info" %} +deBridge flat fees can be changed by governance. Hence, for any on-chain interactions with deBridge, fees **must not** be hardcoded but queried dynamically from the state of the DebridgeGate smart contract. +{% endhint %} + +### Current flat fee for messages sent from different chains + +| Chain | Chain Id | Message Transfer Fee | Block finality | +| --------- | --------- | -------------------- | ---------------- | +| Arbitrum | 42161 | 0.001 ETH | 12 | +| Avalanche | 43114 | 0.05 AVAX | 12 | +| BNB Chain | 56 | 0.005 BNB | 12 | +| Ethereum | 1 | 0.001 ETH | 12 | +| Polygon | 137 | 0.5 MATIC | 256 | +| Fantom | 250 | 4 FTM | 12 | +| Solana | 7565164 | 0.03 SOL | Status Finalized | +| Linea | 59144 | 0.001 ETH | 12 | +| Optimism | 10 | 0.001 ETH | 12 | +| Base | 8453 | 0.001 ETH | 12 | +| Neon | 245022934 | 0.75 NEON | 32 | +| Gnosis | 100 | 1 xDAI | 12 | +| Lightlink | 1890 | 0.0005 ETH | 12 | +| Metis | 1088 | 0.02 METIS | 12 | + diff --git a/docs/the-core-protocol/protocol-overview.md b/docs/the-debridge-messaging-protocol/protocol-overview.md similarity index 74% rename from docs/the-core-protocol/protocol-overview.md rename to docs/the-debridge-messaging-protocol/protocol-overview.md index 4068d70b..f0d9da36 100644 --- a/docs/the-core-protocol/protocol-overview.md +++ b/docs/the-debridge-messaging-protocol/protocol-overview.md @@ -4,15 +4,15 @@ For a long time, bridges were viewed only as value transfer protocols and custodians that are responsible for locking assets on the source chain and issuing wrapped representations of the assets on the destination chain. -deBridge protocol drastically expands the concept of traditional bridges by introducing generic cross-chain message transfers. Now developers and builders can interconnect any smart contracts across different blockchains to perform transfers of data and transaction calls (messages that contain instructions to be executed, or `CALLDATA`) together with the value transfer in the same transaction. +The deBridge protocol drastically expands the concept of traditional bridges by introducing generic cross-chain message transfers. Now developers and builders can interconnect any smart contracts across different blockchains to perform transfers of data and transaction calls (messages that contain instructions to be executed, or `CALLDATA`) together with the value transfer in the same transaction. This opens up endless opportunities to build complex cross-chain interactions, such as multi-chain applications, next-layer protocols, automated cross-chain arbitraging services, object or NFT bridges, and more! As a generic messaging protocol and a cross-chain interoperability infrastructure, deBridge can be used to build any arbitrary cross-chain applications (deApps). Notable solutions built on top of deBridge are: -* [DLN](https://dln.trade/) — a high-performance cross-chain trading infrastructure built on deBridge with 0-TVL design (no liquidity pools). -* [dePort](https://app.debridge.finance/deport) — a native bridge for assets that allows protocols to bridge tokens and create utility for their synthetic representation (deTokens) in other chains -* deNFT — an infrastructure for cross-chain NFT transfers and a solution to create cross-chain native NFTs (coming soon) +* deBridge Liquidity Network Protocol (DLN) — a high-performance cross-chain value transfer infrastructure built on deBridge with 0-TVL design (no liquidity pools). +* [dePort](https://app.debridge.finance/deport) — a native bridge for assets that allows protocols to bridge tokens and create utility for their synthetic representation (deTokens) in other chains. +* deNFT — an infrastructure for cross-chain NFT transfers and a solution to create cross-chain native NFTs (coming soon). Your application can be the next one and this documentation and tutorials will help to dive into the protocol infrastructure and elaborate on questions you might face while building your integration with deBridge. @@ -21,9 +21,9 @@ Your application can be the next one and this documentation and tutorials will h The protocol consists of 2 key layers: * Protocol layer — on-chain smart contracts deployed in every blockchain supported by deBridge -* Infrastructure layer — off-chain validation nodes operated by validators who are elected by deBridge governance +* Infrastructure layer — off-chain validation nodes operated by validators who are elected by the deBridge governance -![](../.gitbook/assets/C.png) +
**The protocol layer** is a set of on-chain smart contracts used for asset management, routing of cross-chain transactions, cross-validation of validators' signatures, and reaching consensus among validators as the transaction is treated as valid only if the minimum required threshold of validators' signatures is achieved. The governance manages the parameters of the smart contracts, such as fees, supported chains, the whitelist of elected validators, validators payout ratio, and more. @@ -35,7 +35,7 @@ For all bridging protocols, it’s important to have a chain-agnostic design and deBridge has taken a unique approach with an off-chain transaction validation mechanic where validators don’t need to broadcast any transactions and bear gas costs. Every cross-chain transaction initiated through the deBridge smart contract is assigned a unique hash (Submission Id). deBridge validators are tracking all transactions that pass through the smart contract of the protocol and soon as the transaction achieves its finality, each validator is obliged to sign the Submission by its private key. -The resulting signature is saved into Arweave — a decentralized data availability layer. Any arbitrary user or keeper can collect validator signatures from Arweave and pass them to the DebridgeGate smart contract in the target chain alongside all transaction parameters. Based on the passed set of parameters, the deBridge smart contract will restore a unique hash of the transaction and cross-validate its signatures from all designated validators. In case the minimum required number of signatures is valid, the DebridgeGate smart contract delivers the message on the destination chain by executing its' call data. +The resulting signature is saved into Arweave, a decentralized data availability layer. Any arbitrary user or keeper can collect validator signatures from Arweave and pass them to the DebridgeGate smart contract in the target chain alongside all transaction parameters. Based on the passed set of parameters, the deBridge smart contract will restore a unique hash of the transaction and cross-validate its signatures from all designated validators. In case the minimum required number of signatures is valid, the DebridgeGate smart contract delivers the message on the destination chain by executing its' call data. With this design, even in the eventuality that some blockchains experience downtime, deBridge will still remain fully functional and all transactions going to the paused chain will be processed as soon as it resumes operation. @@ -49,9 +49,9 @@ Validators play a crucial role in interoperability protocols since in addition t ## How it works -**deBridge is more than a bridge,** it's a secure interoperability layer for Web3 — a foundational layer that enables users and protocols to transport any arbitrary messages or `CALLDATA` across different chains enabling the ability to create any cross-chain solutions, such as deSwap — value transferring protocol built on top of deBridge +**deBridge is DeFi's internet of liquidity** — a foundational layer that enables users and protocols to transport any arbitrary messages or `CALLDATA` across different chains enabling the ability to create any cross-chain solutions, such as deSwap — value transferring protocol built on top of deBridge. -![](<../.gitbook/assets/image (5).png>) +
The ability to pass arbitrary data opens up opportunities for true cross-chain composability of smart contracts and protocols that can now interact with each other despite they live in different blockchain ecosystems. An example would be an algorithmic stablecoin protocol on Ethereum that opens positions in perpetual markets protocol on Solana or Arbitrum in order to maintain the peg of its asset. @@ -64,7 +64,5 @@ deBridge allows the building of a new generation of cross-chain protocols and ap More information about potential use cases can be found in the [debridge-use-cases.md](../external-links/debridge-use-cases.md "mention") section. -### - diff --git a/docs/the-core-protocol/security.md b/docs/the-debridge-messaging-protocol/security.md similarity index 74% rename from docs/the-core-protocol/security.md rename to docs/the-debridge-messaging-protocol/security.md index f79bf3d5..eece6e86 100644 --- a/docs/the-core-protocol/security.md +++ b/docs/the-debridge-messaging-protocol/security.md @@ -6,7 +6,7 @@ description: Information about deBridge security audit processes and bug bounty ### Has deBridge been audited? -Yes, deBridge smart contracts have been audited by [Halborn](https://halborn.com/), [Zokyo](https://www.zokyo.io/), [Ackee Blockchain](https://ackeeblockchain.com/) and [Neodyme](https://neodyme.io/). +Yes, deBridge's smart contracts have been audited by [Halborn](https://halborn.com/), [Zokyo](https://www.zokyo.io/), [Ackee Blockchain](https://ackeeblockchain.com/) and [Neodyme](https://neodyme.io/). Security will always be deBridge's main priority and it is vital for the protocol to be reliable and secure at all times. It’s one of the main components that will determine the future progression of cross-chain interoperability, and as such the deBridge team will maintain this as a main focus area both before and after the protocol launch. @@ -14,7 +14,7 @@ Some of our key focus areas and security strategies can be found in [this blog p ### Third-party security audits -deBridge protocol and periphery modules passed more than 15 security audits. A comprehensive list of audit reports can be found in the [deBridge GitHub repository](https://github.com/debridge-finance/debridge-security). +deBridge protocol and periphery modules passed more than 25+ security audits. A comprehensive list of audit reports can be found in the [deBridge GitHub repository](https://github.com/debridge-finance/debridge-security). ### Immunefi bug bounty program diff --git a/docs/the-core-protocol/slashing-and-delegated-staking.md b/docs/the-debridge-messaging-protocol/slashing-and-delegated-staking.md similarity index 88% rename from docs/the-core-protocol/slashing-and-delegated-staking.md rename to docs/the-debridge-messaging-protocol/slashing-and-delegated-staking.md index cd959855..e462249e 100644 --- a/docs/the-core-protocol/slashing-and-delegated-staking.md +++ b/docs/the-debridge-messaging-protocol/slashing-and-delegated-staking.md @@ -1,12 +1,12 @@ --- description: >- - Delegated staking module will be deployed after deBridge governance token is - live + Delegated staking module will be deployed after the deBridge governance token + is live --- # Slashing and Delegated Staking -
+
Delegated staking and slashing mechanics act as a backbone of protocol security and prevent economic incentives for validators to get into collusion and forge messages. @@ -38,7 +38,7 @@ Once unstaking or transfer of stake has been initiated, the delegator stops rece ### Fees Distribution -As described in Protocol Overview, deBridge infrastructure applies a small fee for each message and value transfer. Half of these fees are transferred to the deBridge treasury controlled by governance. Another half is converted into **ETH** and used as a payout to validators and their delegators. Each payout is evenly distributed among all active validators. +As described in the protocol overview, deBridge infrastructure applies a small fee for each message and value transfer. Half of these fees are transferred to the deBridge treasury controlled by governance. Another half is converted into **ETH** and used as a payout to validators and their delegators. Each payout is evenly distributed among all active validators. Each validator assigns a portion of protocol payouts `profitSharingBPS` to be shared with delegators. These basis points allow the validator to control the ratio between personal/attracted amounts of liquidity. Governance can set a minimum value of this parameter to avoid a situation when validators with a low personal stake assign `profitSharingBPS` close to zero to receive all the protocol payouts and limit the collateral of the protocol.