Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

first pass at updating RFQ relayer documentation #3000

Merged
merged 5 commits into from
Aug 22, 2024
Merged

first pass at updating RFQ relayer documentation #3000

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
06dfc50
first pass
Defi-Moses Aug 9, 2024
1461e3a
extra comments
Defi-Moses Aug 9, 2024
85cc702
fixing internal link
Defi-Moses Aug 13, 2024
480ccf2
resolving conflicts
Defi-Moses Aug 22, 2024
60e7cbf
fix build
Defi-Moses Aug 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/bridge/docs/rfq/API/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,13 @@ Only Solvers should be writing to the API, end-users need only read from the `/q

In accordance with [EIP-191](https://eips.ethereum.org/EIPS/eip-191), the RFQ API requires a signature to be sent with each request. The signature should be generated by the user's wallet and should be a valid signature of the message `rfq-api` with the user's private key. The signature should be sent in the `Authorization` header of the request. We provide a client stub/example implementation in go [here](https://pkg.go.dev/github.com/synapsecns/sanguine/services/rfq@v0.13.3/api/client).

:::note

The RFQ API expects the signatures to have V values as 0/1 rather than 27/28. The fastest way to fix this is to modify V by subtracting 27

:::


### API Urls

- mainnet: rfq-api.omnirpc.io
Expand Down
24 changes: 23 additions & 1 deletion docs/bridge/docs/rfq/Contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,15 @@ The Synapse RFQ contract source code can be found [here](https://github.com/syna
| Optimism | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://optimistic.etherscan.io/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E) |
| Scroll | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://scrollscan.com/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E) |
| Linea | [0x34F52752975222d5994C206cE08C1d5B329f24dD](https://lineascan.build/address/0x34F52752975222d5994C206cE08C1d5B329f24dD) |
<<<<<<< HEAD
| BNB Chain| [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://bscscan.com/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E) |
| Blast | [0x34F52752975222d5994C206cE08C1d5B329f24dD](https://blastscan.io/address/0x34F52752975222d5994C206cE08C1d5B329f24dD) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fix table formatting issues.

The table is missing leading and trailing pipes, and the row for "BNB Chain" has too few cells.

Apply this diff to fix the table formatting:

 | Chain    | Address                                                                                                                          |
 | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
 | Arbitrum | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://arbiscan.io/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E)             |
 | Base     | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://basescan.org/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E)            |
 | Ethereum | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://etherscan.io/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E)            |
 | Optimism | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://optimistic.etherscan.io/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E) |
 | Scroll   | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://scrollscan.com/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E)          |
 | Linea    | [0x34F52752975222d5994C206cE08C1d5B329f24dD](https://lineascan.build/address/0x34F52752975222d5994C206cE08C1d5B329f24dD)         |
+| BNB Chain| [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://bscscan.com/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E)             |
+| Blast    | [0x34F52752975222d5994C206cE08C1d5B329f24dD](https://blastscan.io/address/0x34F52752975222d5994C206cE08C1d5B329f24dD)            |

Committable suggestion was skipped due to low confidence.

Tools
Markdownlint

13-13: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing leading pipe
Table pipe style

(MD055, table-pipe-style)

13-13: Expected: leading_and_trailing; Actual: no_leading_or_trailing; Missing trailing pipe
Table pipe style

(MD055, table-pipe-style)

13-13: Expected: 2; Actual: 1; Too few cells, row will be missing data
Table column count

(MD056, table-column-count)



=======
| Blast | [0x34F52752975222d5994C206cE08C1d5B329f24dD](https://blastscan.io/address/0x34F52752975222d5994C206cE08C1d5B329f24dD) |
| BSC | [0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E](https://bscscan.com/address/0x5523D3c98809DdDB82C686E152F5C58B1B0fB59E) |
>>>>>>> master

### On-Chain Architecture & Transaction Flow

Expand All @@ -20,7 +27,7 @@ The RFQ contract allows users to post bridge requests based on quotes they have
1. **User calls bridge**: The user calls the bridge contract with the quote they have received from the RFQ API and passing in origin, destination and other paramaters as a [BridgeParam](https://vercel-rfq-docs.vercel.app/contracts/interfaces/IFastBridge.sol/interface.IFastBridge.html#bridgeparams).
2. **Bridge emits event**: The bridge contract emits a [`BridgeRequested`](https://vercel-rfq-docs.vercel.app/contracts/interfaces/IFastBridge.sol/interface.IFastBridge.html#bridgerequested) event.
3. **Solver relays request**: The solver relays the request by calling the [`relay`](https://vercel-rfq-docs.vercel.app/contracts/FastBridge.sol/contract.FastBridge.html#relay) function on the RFQ contract. The contract then pulls the tokens from the solvers wallet (or [msg.value](https://ethereum.stackexchange.com/questions/43362/what-is-msg-value) in the case of eth) and sends them to the user filling their order.
4. **Solver Calls Prove**: The solver then calls the [`prove`](https://vercel-rfq-docs.vercel.app/contracts/FastBridge.sol/contract.FastBridge.html#prove) function on the RFQ contract to prove they have filled the order.
4. **Solver Calls Prove**: The solver then calls the [`prove`](https://vercel-rfq-docs.vercel.app/contracts/FastBridge.sol/contract.FastBridge.html#prove) function on the RFQ contract to prove they have filled the order. In the current implementation, the function must be called from the solver address.
5. **User Claims**: If the solver does not call prove within the optimistic window, the user can call the [`claim`](https://vercel-rfq-docs.vercel.app/contracts/FastBridge.sol/contract.FastBridge.html#claim) function to claim their funds back.

### On-Chain Statuses
Expand All @@ -34,3 +41,18 @@ Like the relayer, each transaction in the RFQ contract has a status. The statuse
| Relayer Proved | 2 | The relayer has tried to [`prove`](https://vercel-rfq-docs.vercel.app/contracts/FastBridge.sol/contract.FastBridge.html#prove) the transaction, but cannot claim yet. |
| Relayer Claimed | 3 | The relayer has called [`claim`](https://vercel-rfq-docs.vercel.app/contracts/FastBridge.sol/contract.FastBridge.html#claim) and gotten the funds. |
| Refunded | 4 | The relayer has not called `claim` within the optimistic period or a dispute has been decided in favor of the user and the users been refunded. |


### Dispute Period and Guards

The RFQ system includes a dispute period and guards to ensure the integrity of bridge transactions. Here's how it works:

After a relayer submits a proof for a bridge transaction, there's a set period during which the transaction can be disputed. This period allows for detection and correction of any errors or fraudulent activities. Guards are responsible for monitoring bridge transactions and initiating disputes if they detect issues such as incorrect fill amounts and proofs submitted by the wrong relayer. A successful dispute would end up with the relayer losing their claimable funds.

The current implementation is architectured to enforce honest behavior and also protect honest relayers in cases of blockchain reorgs.

### Other Functionalities

**ChainGas**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use a heading instead of emphasis for "ChainGas".

The static analysis tool suggests using a heading instead of emphasis for "ChainGas" to maintain consistency with other sections.

Apply this diff to fix the heading:

-**ChainGas**
+### ChainGas
Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**ChainGas**
### ChainGas
Tools
Markdownlint

49-49: null
Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)


`sendChainGas` is a field that is populated by the bridge user, and it's a simple bool flag. If `sendChainGas=true` the amount is specified in the FastBridge contract on the destination chain as `chainGasAmount`. This is currently set to zero in all the contracts, and can thus be ignored by filling orders with either no `sendChainGas` option (or to chains with `chainGasAmount==0`)
13 changes: 10 additions & 3 deletions docs/bridge/docs/rfq/Relayer/Relayer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@
sidebar_position: 0
sidebar_label: Relayer
---
:::note

Relayers must be whitelisted in order to fill bridgeRequests.

:::

At a high level, the canonical implementation of the relayer has 3 different responsibilities.

Expand All @@ -23,13 +27,16 @@ The quoting loop is comparitively simple and updates the api on each route it su

### Rebalancing

The rebalancing loop is more complex and is responsible for ensuring that the relayer has enough liquidity on each chain. Right now only the CCTP rebalancer is supported and works like this:
The rebalancing loop is more complex and is responsible for ensuring that the relayer has enough liquidity on each chain. The CCTP rebalancer is supported and works like this:

1. At `rebalance_interval`, check the `maintenance_balance_pct` of each token on each chain and compare it to the current balance. If the balance is below the `maintenance_balance_pct`, continue
2. Calculate the amount to rebalance by taking the difference between the maintenance balance and the current balance and multiplying it by the `initial_balance_pct`.
3. If the amount to rebalance is greater than the `max_rebalance_amount`, set the amount to rebalance to the `max_rebalance_amount`. If the amount to rebalance is less than the `min_rebalance_amount`, do not rebalance.
4. Repeat after `rebalance_interval`

The implementation for certain native bridges (e.g Scroll) is also supported. It works slightly differently as flows are only supported between Scroll and Mainnet. At a high level, the rebalancer checks inventory on Scroll versus other chains, and if imbalanced, initiates a bridge to mainnet, allowing the CCTP relayer to rebalance funds where needed.

Comment on lines +30 to +38
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fix grammar issue in rebalancing section.

There is a missing preposition in the sentence "If the balance is below the maintenance_balance_pct, continue".

Apply this diff to fix the grammar issue:

 1. At `rebalance_interval`, check the `maintenance_balance_pct` of each token on each chain and compare it to the current balance. If the balance is below the `maintenance_balance_pct`, continue
+   with the rebalancing process.

The section provides a detailed explanation of the rebalancing process, including support for native bridges.

Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The rebalancing loop is more complex and is responsible for ensuring that the relayer has enough liquidity on each chain. The CCTP rebalancer is supported and works like this:
1. At `rebalance_interval`, check the `maintenance_balance_pct` of each token on each chain and compare it to the current balance. If the balance is below the `maintenance_balance_pct`, continue
2. Calculate the amount to rebalance by taking the difference between the maintenance balance and the current balance and multiplying it by the `initial_balance_pct`.
3. If the amount to rebalance is greater than the `max_rebalance_amount`, set the amount to rebalance to the `max_rebalance_amount`. If the amount to rebalance is less than the `min_rebalance_amount`, do not rebalance.
4. Repeat after `rebalance_interval`
The implementation for certain native bridges (e.g Scroll) is also supported. It works slightly differently as flows are only supported between Scroll and Mainnet. At a high level, the rebalancer checks inventory on Scroll versus other chains, and if imbalanced, initiates a bridge to mainnet, allowing the CCTP relayer to rebalance funds where needed.
The rebalancing loop is more complex and is responsible for ensuring that the relayer has enough liquidity on each chain. The CCTP rebalancer is supported and works like this:
1. At `rebalance_interval`, check the `maintenance_balance_pct` of each token on each chain and compare it to the current balance. If the balance is below the `maintenance_balance_pct`, continue with the rebalancing process.
2. Calculate the amount to rebalance by taking the difference between the maintenance balance and the current balance and multiplying it by the `initial_balance_pct`.
3. If the amount to rebalance is greater than the `max_rebalance_amount`, set the amount to rebalance to the `max_rebalance_amount`. If the amount to rebalance is less than the `min_rebalance_amount`, do not rebalance.
4. Repeat after `rebalance_interval`
The implementation for certain native bridges (e.g Scroll) is also supported. It works slightly differently as flows are only supported between Scroll and Mainnet. At a high level, the rebalancer checks inventory on Scroll versus other chains, and if imbalanced, initiates a bridge to mainnet, allowing the CCTP relayer to rebalance funds where needed.
Tools
LanguageTool

[grammar] ~32-~32: Probably a preposition is missing after ‘continue’.
Context: ...is below the maintenance_balance_pct, continue 2. Calculate the amount to rebalance by taking the d...

(ATD_VERBS_TO_COLLOCATION)

[style] ~34-~34: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...ebalance to the max_rebalance_amount. If the amount to rebalance is less than th...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

[uncategorized] ~37-~37: The abbreviation “e.g.” (= for example) requires two periods.
Context: ...lementation for certain native bridges (e.g Scroll) is also supported. It works sli...

(E_G)

[uncategorized] ~37-~37: Possible missing comma found.
Context: ...l) is also supported. It works slightly differently as flows are only supported between Scr...

(AI_HYDRA_LEO_MISSING_COMMA)


### Relaying

The relaying loop is the most complex and is responsible for relaying funds on-chain. The relayer listens to events on-chain and status updates in the database to take move transactions through the states. The states are as follows:
Expand Down Expand Up @@ -104,7 +111,7 @@ The relayer is configured with a yaml file. The following is an example configur

screener_api_url: 'http://screener-url' # can be left blank
rfq_url: 'http://rfq-api' # url of the rfq api backend.
omnirpc_url: 'http://omnirpc' # url of the omnirpc instance
omnirpc_url: 'http://omnirpc' # url of the omnirpc instance, please reference the Omnirpc section under Services for proper configuration
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fix bare URL issue in configuration section.

There are bare URLs in the configuration section that should be formatted as links.

Apply this diff to fix the bare URL issue:

- omnirpc_url: 'http://omnirpc' # url of the omnirpc instance, please reference the Omnirpc section under Services for proper configuration
+ omnirpc_url: '[http://omnirpc](http://omnirpc)' # url of the omnirpc instance, please reference the Omnirpc section under Services for proper configuration

- base_omnirpc_url: "http://omnirpc" # Make sure this is configured properly
+ base_omnirpc_url: "[http://omnirpc](http://omnirpc)" # Make sure this is configured properly

The section provides a detailed explanation of the configuration parameters for the relayer.

Also applies to: 200-200

Tools
Markdownlint

114-114: null
Bare URL used

(MD034, no-bare-urls)

rebalance_interval: 2m # how often to rebalance
relayer_api_port: '8081' # api port for the relayer api

Expand Down Expand Up @@ -190,7 +197,7 @@ The relayer is configured with a yaml file. The following is an example configur
- chain_id: 10
synapse_cctp_address: "0x12715a66773BD9C54534a01aBF01d05F6B4Bd35E"
token_messenger_address: "0x2B4069517957735bE00ceE0fadAE88a26365528f"
base_omnirpc_url: "http://omnirpc"
base_omnirpc_url: "http://omnirpc" # Make sure this is configured properly
unbonded_signer:
type: GCP
file: /config/signer.txt
Expand Down
Loading