The Reservoir relayer is a production-grade relayer currently supporting Relay. Reservoir acts as a trusted party that performs cross-chain relays and order validation.

​
How does it work?

When a user wishes to bridge, they submit an order and a transfer to the Reservoir relayer, who validates the order and sends the funds to the user on the destination chain. Reservoir maintains a balance on all chains in order to make executions, and then periodically rebalances to ensure there is sufficient liquidity on all chains. In the rare case of a transaction failure, Reservoir refunds the user directly as soon as possible. While this model requires trust in Reservoir as a service provider, it reduces the costs of executing cross-chain actions to an absolute minimum. Since each cross-chain action is simply an origin chain transfer and a destination chain transfer (42000 gas total), it is substantively cheaper than bridging on other bridges.

​
Why start with a trusted system?

The current state of Relay, which requires trust in Reservoir’s relayer, is an important part of the protocol development process. It is not intended as a final state of the system, but as a way to introduce the core concepts, and learn from users, developers, and relayers about what is most important in the future decentralized system. If you are interested in learning more about where Relay is headed, you can read the protocol overview here.

​
Technical overview

Here we walk through some technical details about how the Reservoir relayer functions.

​
Getting a quote

When a user wishes to Relay, the application receives an order (quote) from the Relay SDK/API. The quote returns both a cost for execution, and an expected time. The quote is a total value required by the user for the action to proceed. The quote encompasses the execution value, the estimated destination chain gas fee, and the relayer fee. This quote covers the gas cost on the destination chain. The transfer call data for order acceptance is also included in the returned data.

​
Quote Execution Flow:

  • User gets a quote which is valid for 30 seconds.
  • If the user submits within 30 seconds, the solver will fill the request.
  • If the user doesn’t submit in time, the solver will get a fresh quote.
  • If the new quote is higher than the old one, the fallback flow is triggered.
  • If the new quote is less than or equal to the old one, the solver proceeds with the request.
  • In the fallback case, the user is refunded either on the destination (default) or origin chain. (The refundOnOrigin param can be passed into the bridge/call apis and sdk actions to override the refund logic)
Note: Because quotes can go stale after 30 seconds, it is crucial for the client to regularly fetch fresh quotes so that users are always submitting valid transactions.

​
Onchain order attribution

When the user accepts the order, they submit a transfer to the solver. An order ID associated with the quote is appended in the tx calldata. This order ID will be used on the destination chain to link fills across chains.

​
Order validation and filling

Upon validation of the inbound transfer transaction, the Reservoir relayer will fill the order on the destination chain. Included in the fill transaction is the order ID associated with the quote. Reservoir maps the origin and destination chain transactions together by order ID to ensure the transaction is filled appropriately.

​
Rebalancing

The Reservoir relayer uses a robust rebalancing algorithm to make sure funds are as available as possible for cross-chain executions. The user is not responsible for any rebalancing activity. If the Reservoir relayer becomes “off-balance”, the capacity for instant relaying may be limited.

​
Refunds

If for some reason the quoted execution is no longer available by the time of relay submission, the user may be refunded. Refunds are as instant as possible and are refunded on the destination chain by default, and the origin chain otherwise. The refundOnOrigin param can be passed into the bridge/call apis and sdk actions to override the refund logic.

​
Partial fills

If the user submits the transfer event after quote expiration, the relayer may not be able to fill the order at the quoted price if gas prices on the destination chain have increased substantially. In this case, the relayer will attempt to fill the order at the best possible price, and give the rest of the bridged value to the user.

​
Disputes

Due to the trusted nature of the current Relay design, disputes (i.e. cases where a user did not receive the expected outcome and was not refunded) should be brought directly to the Reservoir support team.