From 50acd512ebadfa0152dbfc09de0ceb1609eac984 Mon Sep 17 00:00:00 2001 From: ChiTimesChi <88190723+ChiTimesChi@users.noreply.github.com> Date: Mon, 24 Jul 2023 18:17:38 +0100 Subject: [PATCH 01/15] Add bridging workflow --- contracts/router/docs/README.md | 54 +++++++++++++++ contracts/router/docs/bridge.dot | 111 +++++++++++++++++++++++++++++++ contracts/router/docs/bridge.png | Bin 0 -> 123761 bytes 3 files changed, 165 insertions(+) create mode 100644 contracts/router/docs/README.md create mode 100644 contracts/router/docs/bridge.dot create mode 100644 contracts/router/docs/bridge.png diff --git a/contracts/router/docs/README.md b/contracts/router/docs/README.md new file mode 100644 index 000000000..757edc25a --- /dev/null +++ b/contracts/router/docs/README.md @@ -0,0 +1,54 @@ +# SynapseRouterV2 workflows + +## Bridging + +Bridging is exposed using `SynapseRouterV2.bridgeViaSynapse()` method. User can specify the optional swap to be taken on both origin and destination chains. + +### Function parameters + +| Parameter | Type | Description | +| ----------- | --------- | ------------------------------------------------------------ | +| recipient | address | User address on the destination chain | +| chainId | uint256 | Destination chain id | +| token | address | Initial token address on the origin chain | +| amount | uint256 | Initial token amount | +| tokenSymbol | string | Symbol of a token that will be bridged | +| originQuery | SwapQuery | Information about the optional swap on the origin chain | +| destQuery | SwapQuery | Information about the optional swap on the destination chain | + +### `SwapQuery` structure + +| Parameter | Type | Description | +| ------------- | ------- | -------------------------------------------------------------------- | +| routerAdapter | address | Address of the router adapter that will perform the swap | +| tokenOut | address | Token address that will be received after the swap | +| minAmountOut | uint256 | Minimum amount of the token that will be received, or tx will revert | +| deadline | uint256 | Deadline for the swap, or tx will revert | +| rawParams | bytes | Raw bytes parameters that will be passed to the router adapter | + +> For swaps using Default Pools `routerAdapter` is set to `synapseRouterV2` address, which inherits from `DefaultAdapter`. These are whitelisted pools that allow swaps between correlated tokens. +> +> - Alternative adapters can be used to perform complex swaps, but only on the origin chain. +> - Only whitelisted pools are allowed for destination swaps, therefore only `synapseRouterV2` can be used as `routerAdapter` on the destination chain. +> - `routerAdapter` for both `originQuery` and `destQuery` can be set to `address(0)`, which will skip the swap on the given chain. + +> Note: `minAmountOut` and `deadline` are used to prevent front-running attacks. +> +> - If swap on origin chain fails, the whole transaction will revert, and no bridging happens. +> - If swap on destination chain fails, user receives the bridged token on destination chain instead of `tokenOut`. + +### Bridging workflow + +1. User calls `SynapseRouterV2.bridgeViaSynapse()` method on the origin chain. + > User needs to approve `SynapseRouterV2` for spending `token` before calling this method. +2. Based on the `tokenSymbol` the address of the Bridge Adapter supporting given symbol is determined. + > - `originQuery.tokenOut` needs to match `tokenSymbol`, or the transaction will revert. + > - Transaction will also revert, if `tokenSymbol` is not supported by any Bridge Adapter. +3. `(token, amount)` is pulled from the user, and transferred to the `originQuery.routerAdapter`. +4. `originQuery.routerAdapter` is called to perform a swap on the origin chain. + > - Swap from `token` to `originQuery.tokenOut` will be performed. +5. The Router Adapter performs a swap, and transfers `tokenOut` to the `BridgeAdapter` contract. + > - Note: if `originQuery.routerAdapter` is empty, steps 3-5 are skipped, and `(token, amount)` is pulled from user to the `BridgeAdapter` contract instead. +6. `BridgeAdapter` is called to initiate the bridging to destination chain. + +![Bridging workflow](./bridge.png) diff --git a/contracts/router/docs/bridge.dot b/contracts/router/docs/bridge.dot new file mode 100644 index 000000000..45f3c200d --- /dev/null +++ b/contracts/router/docs/bridge.dot @@ -0,0 +1,111 @@ +digraph { + user [label = "User EOA";]; + router [label = "SynapseRouterV2";shape = rect;]; + routerAdapter [label = "RouterAdapter";shape = rect;]; + bridgeAdapter [label = "BridgeAdapter";shape = rect;]; + bridge [label = "SynapseBridge | SynapseCCTP | ...";shape = rect;]; + node [shape = none; fontname = "Arial";]; + routerBridge [label = < +
Function | +synapseRouterV2.bridgeViaSynapse | +
Parameters | +recipient, chainId, token, amount, tokenSymbol, originQuery, destQuery | +
Description | +Peforms a swap, then bridges swapped token via a Synapse solution | +
Function | +originQuery.routerAdapter.adapterSwap | +
Parameters | +SynapseRouterV2, token, amount, originQuery.tokenOut, originQuery.rawParams | +
Output | +return amountOut; | +
Description | +Performs an arbitrary swap on the origin chain | +
Function | +synapseRouterV2.getBridgeAdapter | +
Parameters | +tokenSymbol | +
Output | +return bridgeAdapter; | +
Description | +Fetches the bridge adapter for a given bridge token symbol | +
Function | +bridgeAdapter.adapterBridge | +
Parameters | +recipient, chainId, tokenOut, amountOut, destQuery | +
Description | +Performs a bridge operation to the destination chain | +
9P{y`
z9*LEsm51!U`0DS|Qyx joKy|i8Px--dIQIM9y(@+%1
z-(tw%@pG-lHz`)BW&%0K9y}N=7IGY(qcI?-%MVbn+CRUF^>3hBt|kX
zZ7&V0gvS{HQURoPsx^ZFm~P*hGs4&CSQg?z5f$i4JA13}IFd(Om(kNJDkv;PC*~43
zq@r?FiJNaol{eCCfl<3`X`pKLc$#RZ&&`|rbaa^D!qBs^6|Q|}-&?mF^Dk#_FUG#d
z-5Z$>t{pqp!jE_hw~8!1s*0h->u4aXx6RG0xWVx;#e4-Mp4E_0&}0ixyY`lB2t)N)
zKv}wUsa~G@ZamDLJ9j*RM9g4Uy?F5=AFrh`;4v5a D8DoYw240-BDRF8-*oHo*J
z20CDXVZIcpV0=nyh+%Dr@fJX=I=Z^m2~!9=t}rAyW%94D+)U{^h&!zMO531Unri|e
z2N4+9Fm2@l6FchHGU#^3?AIbUX^TV(lqm&gV=>H^0V1TnYr&5nM>yBPGvL$b&w)o*
zP@PCumVAu4LT%8bZvfd$Ys71qF&Nnc6<8;!pR+Pv-P)1!>Xo5)lW#$|@)AcotokTs
zZRjtjRK^OYkfdd+V{88kAI{f_qLR*2ceg=`D%xxcEZUQ9@Y#KcHd7FM=3$A1cZENR
z;pcH_R#wg;VVAcebJQzu7VnGpmC>+so}Sr&%?YPZ=XRIa71{OIgI+d8