+```solidity + function relayV2(bytes memory request, address relayer) external payable; +``` +This version allows an arbitrary `relayer` address to be supplied ++
+```solidity + function relay(bytes memory request) external payable; +``` +This version will auto-assign the executing EOA (`msg.sender`) as the `relayer` ++
+```solidity + function proveV2(bytes32 transactionId, bytes32 destTxHash, address relayer) external; +``` +This version allows an arbitrary `relayer` address to be supplied ++ +
+```solidity + function prove(bytes memory request, bytes32 destTxHash) external; +``` +This version will auto-assign the executing EOA (`msg.sender`) as the `relayer` ++
+```solidity + function claimV2(bytes memory request) external; +``` +This version can only be executed by the `relayer` on the proof. Allows an arbitrary `to` address as the recipient of funds. ++
+```solidity + function claim(bytes memory request, address to) external; +``` + + +This version can be executed permissionlessly, and will transfer the funds only to the `relayer` address on the proof. ++
+#### [canClaim](https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridge.sol/interface.IFastBridge.html#canclaim) + +Checks if the [Dispute Period] has passed and the funds are now claimable + +##### [bridgeStatuses](https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#bridgestatuses) + +Returns the current [BridgeStatus](https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#bridgestatus) of the indicated `transactionId` + +##### [bridgeProofs](https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#bridgeproofs) + +Returns the details of a bridge proof, including the asserted `relayer` + +#### [getBridgeTransaction](https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#getbridgetransactionv2) + +Decodes request bytes (such as those emitted from a [BridgeRequested] event) into a [BridgeTransactionV2] struct. ++ +### Call from Destination Chain: +
+##### [bridgeRelays](https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#bridgerelays) + +Checks if the indicated `transactionId` has already been relayed ++ +## RFQ Load Tester + +The [`rfq-loadtest`](https://github.com/synapsecns/sanguine/tree/master/packages/rfq-loadtest) tool can be used to rapidly send ETH bridges for the purpose of load testing. diff --git a/docs/bridge/docs/03-RFQ/index.md b/docs/bridge/docs/03-RFQ/index.md new file mode 100644 index 0000000000..cef0db07a9 --- /dev/null +++ b/docs/bridge/docs/03-RFQ/index.md @@ -0,0 +1,210 @@ +--- +title: Synapse Intent Network +--- + +import { RFQFlow } from '@site/src/components/RFQFlow' + + +[relay]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#relayv2 +[prove]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#provev2 +[dispute]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridge.sol/interface.IFastBridge.html#dispute +[claim]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#claimv2 +[cancel]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#cancelv2 +[proof]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#bridgetxdetails +[BridgeRequested]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridge.sol/interface.IFastBridge.html#bridgerequested +[BridgeTransactionV2]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridgeV2.sol/interface.IFastBridgeV2.html#bridgetransactionv2 +[BridgeRelayed]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridge.sol/interface.IFastBridge.html#bridgerelayed +[BridgeProofProvided]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IFastBridge.sol/interface.IFastBridge.html#bridgeproofprovided +[Cancel Delay]: https://rfq-contracts.synapseprotocol.com/contracts/FastBridge.sol/contract.FastBridge.html#refund_delay +[Multicall]: https://rfq-contracts.synapseprotocol.com/contracts/interfaces/IMulticallTarget.sol/interface.IMulticallTarget.html + +[Quoter API]: /docs/RFQ/Quoting/Quoter%20API/ +[Dispute Period]: /docs/RFQ/Security/#dispute-period +[Quoting]: /docs/RFQ/Quoting +[Bridging]: /docs/RFQ/Bridging +[Relaying]: /docs/RFQ/Relaying +[Proving]: /docs/RFQ/Proving +[Claiming]: /docs/RFQ/Claiming +[Canceling]: /docs/RFQ/Canceling +[Security]: /docs/RFQ/Security +[Exclusivity]: /docs/RFQ/Exclusivity + +[User]: /docs/RFQ/#entities +[Quoter]: /docs/RFQ/#entities +[Prover]: /docs/RFQ/#entities +[Relayer]: /docs/RFQ/#entities +[Guard]: /docs/RFQ/#entities +[Canceler]: /docs/RFQ/#entities + +# Synapse Intent Network + +Synapse Intent Network (SIN) is an RFQ (Request-For-Quote) based intent centric bridging system that connects bridging users to a network of relayers. + +These relayers compete to provide the optimal bridge execution (eg: the best price) for the user's specific request. + +
| Order | +User inputs their desired order into a bridge interface. | +
| Quote | +Quotes from Relayers are evaluated and resolved to the optimal choice to match the user's input.
+ The resolved quote is used to construct a bridge transaction for the user to sign. |
+
| Request | +User signs and submits the bridge transaction on-chain.
+ Their assets are deposited into a Bridge contract on the `originChain`. |
+
| Relay | +A [Relayer] completes the user's bridge on the `destChain` by delivering the user's desired funds.
+ At this point, the bridge is complete from the user's perspective. |
+
| Prove | +The [Relayer] submits an optimistic proof of their completed relay to the `originChain`. | +
| Guard | +After a proof is asserted for each bridge, a brief optimistic dispute period is initiated.
+ During this period, [Guard] entities will verify that the proof is valid and accurate. |
+
| Claim | +After the dispute period has passed, the [Relayer] may claim the user's originally deposited funds.
+ This reimburses the [Relayer] for the funds which they delivered in the earlier [relay] step. |
+
+ Uses a bridge interface to submit their intent to the RFQ system for a quote, and then to the chain for fulfillment. +
+ Posts Passive and/or Active Quotes via the [Quoter API] to be matched against user bridge inputs. + + Note: In practice, each participating Quoter typically acts as their own Relayer and Prover. + +
+ Observes bridge deposits and submits [relay] transactions to fulfill them. + + Also submits `claim` transactions to be reimbursed for their relays. + + Note: In practice, each participating Relayer typically acts as their own Quoter and Prover. +
+ Observes [relay]s and submits [prove] transactions to initiate relayer reimbursements. + + Note: In practice, each participating Prover typically acts as their own Quoter and Relayer. +
+ Validates proofs during the [Dispute Period] and submits [dispute] transactions for any discrepancies found. + + Currently, Synapse itself is the sole Guard operator of the Synapse Intent Network (SIN) system. +
+ Able to manually pre-emptively cancel bridge requests which have been deposited, have not yet been relayed, and are past their relay deadline. + + Currently, Synapse itself is the sole Canceler operator of the Synapse Intent Network (SIN) system. + + Note: Incomplete bridge requests can also be canceled permissionlessly (without any involvement from a Canceler) after a longer cancellation window has passed. ++ + + +## Architecture + +### Quoter API +The RESTful [Quoter API] allows Quoters to post Passive and/or Active Quotes. +These quotes are then used to create transactions for Users to sign and submit. + +### FastBridge Smart Contracts +[Synapse FastBridge contracts](/docs/Contracts/RFQ) facilitate and enforce all of the on-chain functionality and security of the system. + +This includes the bridge, deposit, escrow, and eventual release of user funds on the origin chain. + +Associated [relay], [prove], [claim], [dispute], and [cancel] actions are also facilitated by FastBridge contracts. + +Additionally, the FastBridge contracts manage all relevant permissions and on-chain configuration settings of the system. + +FastBridge contracts will be deployed on all supported chains. + + +## Flow Summary + +#### [Quoting] +
+A [User] inputs their desired bridge information into an bridge interface such as [Synapse](https://synapseprotocol.com/?fromChainId=1). + +Quotes to complete the bridge are collected from [Quoters]. The best of these is resolved and presented to the user as a bridge transaction to sign & submit on-chain. ++ +#### [Bridging] +
+Once the [User] has signed and submitted their deposit on-chain via a bridge transaction, the bridging funds will be transferred to a FastBridge contract and held in escrow. + ++ +#### [Relaying] + +
+Relayers who observe the bridge deposit event can permissionlessly complete the bridge by calling [relay] on the FastBridge contract of the destination chain. Typically the Relayer is the same as the Quoter. + +This will transfer the bridge destination funds from the [Relayer] to the [User], with FastBridge acting as intermediary. + +At this point, the process is complete from the [User]'s perspective. However, the [Relayer] needs to be reimbursed for the funds they delivered. ++ +#### [Proving] + +
+ +After the relay, a [Prover] (typically also the Relayer) will submit a [prove] transaction with the relay transaction's details to the origin chain's FastBridge contract. + +This asserts that the [relay] for the bridge was completed according to the specifications of the [User], and that the [Relayer] can rightfully [claim] the escrowed funds. + +A [Dispute Period] begins for the transaction before the [claim] can occur. + ++ +#### [Dispute Period] + +
+During the [Dispute Period], [Guard] entities will verify that the proof's assertion is accurate. + +IE: They will confirm that the [relay] being asserted was completed exactly as specified by the user. + +If any discrepancies are found, the guards will [dispute] the proof ++ +#### [Claiming] + +
+Once the [Dispute Period] has passed without incident, a [claim] transaction can be executed by the [Relayer] on the origin chain. + +This will release the deposit funds from escrow and deliver them to the rightful [Relayer] as a reimbursement for the liquidity they provided on the [relay]. +diff --git a/docs/bridge/docs/04-Routers/RFQ/API/index.md b/docs/bridge/docs/04-Routers/RFQ/API/index.md deleted file mode 100644 index 8abe0acb1e..0000000000 --- a/docs/bridge/docs/04-Routers/RFQ/API/index.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -sidebar_position: 0 -sidebar_label: API ---- - -# RFQ API - -:::note - -This guide is mostly meant for developers who are working on building their own quoter or frontend for rfq. If you are just looking to run a relayer, please see [Relayer](../Relayer). If you are looking to integrate rfq, please see the API docs below the dropdown. - -::: - -The RFQ API is an off-chain service that allows market makers to post quotes for certain bridge routes & tokens. Users can then read these quotes and take the liquidity by submitting a transaction on chain through the [Fast Bridge Contract](https://vercel-rfq-docs.vercel.app/contracts/FastBridge.sol/contract.FastBridge.html). - -Solvers are responsible for keeping quotes fresh and implementations of the RFQ relayer should update quotes as often as possible. By default, the canonical [relayer](../Relayer) continuously updates quotes by checking on-chain balances and in-flight requests and other implementations should take a similar approach. - -The implementation of the rfq api can be found [here](https://github.com/synapsecns/sanguine/tree/master/services/rfq/api). Please note that end-users and solvers will not need to run their own version of the API. - -## Integrating the API - -The RFQ API is a RESTful API that allows users to post quotes and read quotes. The API is incredibly simple and only has one endpoint with two methods: - -- [`PUT /quotes`](./upsert-quote.api.mdx) (authenticated) - Upsert a quote -- [`GET /quotes`](./get-quotes.api.mdx) (unauthenticated) - Get all quotes, can be filtered by different parameters. - -Only Solvers should be writing to the API, end-users need only read from the `/quotes` endpoint. - -**API Version Changes** - -An http response header "X-Api-Version" will be returned on each call response. - -Any systems that integrate with the API should use this header to detect version changes and perform appropriate follow-up actions & alerts. - -Upon a version change, [versions.go](https://github.com/synapsecns/sanguine/blob/master/services/rfq/api/rest/versions.go) can be referred to for further detail on the version including deprecation alerts, etc. - -Please note, while Synapse may choose to take additional steps to alert & advise on API changes through other communication channels, it will remain the responsibility of the API users & integrators to set up their own detection & notifications of version changes as they use these endpoints. Likewise, it will be their responsibility review the versions.go file, to research & understand how any changes may affect their integration, and to implement any necessary adjustments resulting from the API changes. - -**Authentication** - -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: `api.synapseprotocol.com/quotes` - - Testnet: `rfq-api-testnet.omnirpc.io` - - - -## Running the API: - -Users and relayers **are not** expected to run their own version of the RFQ API. The API is a service that should be run by Quoters and interfaces that allow Solvers to post quotes. The RFQ API takes in a yaml config that allows the user to specify which contracts, chains and interfaces it should run on. The config is structured like this: - -```yaml -database: - type: mysql # can be other mysql or sqlite - dsn: root:password@hostname:3306)/database?parseTime=true # should be the dsn of your database. If using sqlite, this can be a path -omnirpc_url: https://route-to-my-omnirpc # omnirpc route -bridges: - 1: '0x00......' # FastBridge address on ethereum (chain id: 1) - 10: '0x01....' # FastBridge address on op (chain id: 10) -port: '8081' # port to run your http server on -``` - -Yaml settings: - -- `database` - The database settings for the API backend. A database is required to store quotes and other information. Using SQLite with a dsn set to a `/tmp/` directory is recommended for development. - - `type` - the database driver to use, can be `mysql` or `sqlite`. - - `dsn` - the dsn of your database. If using sqlite, this can be a path, if using mysql please see [here](https://dev.mysql.com/doc/connector-odbc/en/connector-odbc-configuration.html) for more information. -- `omnirpc_url` - The omnirpc url to use for querying chain data (no trailing slash). For more information on omnirpc, see [here](/docs/Services/Omnirpc). -- `bridges` - A key value map of chain id to FastBridge contract address. The API will only allow quotes to be posted on these chains. -- `port` - The port to run the http server on. - -**Building From Source:** - -To build the RFQ API from source, you will need to clone the repository and run the main.go file with the config file. Building from source requires go 1.21 or higher and is generally not recommended for end-users. - -1. `git clone https://github.com/synapsecns/sanguine --recursive` -2. `cd sanguine/services/rfq` -3. `go run main.go --config /path/to/config.yaml` - -**Running with Docker** - -The RFQ API can also be run with docker. To do this, you will need to build the docker image and run it with the config file. - -:::tip -Docker versions should always be pinned in production environments. For a full list of tags, see [here](https://github.com/synapsecns/sanguine/pkgs/container/sanguine%2Frfq-api) -::: - -1. `docker run ghcr.io/synapsecns/sanguine/rfq-api:latest --config /path/to/config` diff --git a/docs/bridge/docs/04-Routers/RFQ/index.md b/docs/bridge/docs/04-Routers/RFQ/index.md deleted file mode 100644 index b2a498f803..0000000000 --- a/docs/bridge/docs/04-Routers/RFQ/index.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -sidebar_label: RFQ ---- - -import { RFQFlow } from '@site/src/components/RFQFlow' - -# RFQ Router - -A [Synapse Router](../Synapse-Router) bridge module which matches on-chain user requests against bridge quotes posted by decentralized [Relayers](Relayer). - -