certusone
/
xdapp-book
mirror of https://github.com/certusone/xdapp-book.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

relayer: line edits

This commit is contained in:
Eric Wong 2022-09-23 14:21:04 -05:00
parent 0845b5326e
commit 4a9c474bfb
3 changed files with 36 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
src/technical/evm/relayer.md
View File

@ -1,16 +1,16 @@
# Relayer Module
Note: this module is only available in devnet, and is subject to change while still in development.
**_Disclaimer: This module is only available in devnet, and is subject to change while still in development._**
In order to integrate with the relayer module (which enables generic relaying), there are two requirements placed on the integrator.
1. The integrator must implement the `wormholeReceiver` interface, which will be called by the relayer to deliver the requested messages. If the recipient contract does not implement this function on their contract, the delivery will automatically fail.
1. To receive messages, the integrator must implement the `wormholeReceiver` interface, which will be called by the relayer to deliver the requested messages. If the recipient contract does not implement this function on their contract, the delivery will automatically fail.
2. The integrator must request delivery to the target chain via the `requestDelivery(DeliveryInstructions instructions)` function on the relayer module.
2. To request message delivery, the integrator must call the `requestDelivery(DeliveryInstructions instructions)` function on the relayer module.
## Receiving Messages
Receiving messages through the relayer module is almost trivial. Simply implement this public function in your contract.
Receiving messages through the relayer module is almost trivial. Simply implement the public function `wormholeReciever` in your contract that the relayer module will invoke.
```
function wormholeReceiver(
@ -21,19 +21,19 @@ function wormholeReceiver(
)
```
This is the function which will be invoked by the relayer module to deliver messages.
This is the function takes the following four inputs:
- `vaas` are the VAAs which were requested for delivery.
- `sourceChain` is the Wormhole chain ID of the chain the messages were sent from.
- `sourceAddress` is the address which requested delivery. (In Wormhole format!)
- `payload` an additional payload which is at the top level.
- `vaas`: VAAs which were requested for delivery
- `sourceChain`: Wormhole chain ID of the chain the messages were sent from
- `sourceAddress`: address which requested delivery (_In Wormhole format!_)
- `payload`: additional payload which is at the top level
There are only a few noteworthy items here:
There are a few noteworthy items here:
- your `wormholeReceiver` function should never throw an exception. Throwing an exception here will just cause a delivery failure and _will not revert the transaction(!!!)_.
- `wormholeReceiver` will only be called with as much gas as was specified by the compute budget specified by the contract which requested delivery.
- Batch VAAs are always used by the relayer module. `vaas` is an array of all the headless VAAs for which delivery was requested. You still always need to call `core_bridge.parseAndVerifyVM`! The VAAs aren't verified until you have VM objects. (More on this in [Best Practices](./bestPractices.md))
- The generic relay VAA will be included in the `vaas` array you receive. Usually this VAA is ignored, but you can use it if it's useful to you.
- `wormholeReceiver` function should never throw an exception. Throwing an exception here will just cause a delivery failure and _will not revert the transaction(!!!)_.
- `wormholeReceiver` will only be called with as much gas as was specified by the compute budget specified when the message delivery was requested.
- Batch VAAs are always used by the relayer module. `vaas` is an array of all the headless VAAs for which delivery was requested. These VAAs are not verified until you have VM objects which is obtained by calling `core_bridge.parseAndVerifyVM`! (More on this in [Best Practices](./bestPractices.md))
- The generic relay VAA will be included in the `vaas` array you receive. This VAA can be ignored, but you can use it if it's useful to you.
## Sending Messages
@ -54,33 +54,33 @@ struct DeliveryParameters {
}
```
- `targetChain` is the chain Id of the chain this should be delivered to.
- `targetAddress` contract address (in Wormhole format) to deliver to.
- `payload` an additional payload which will be included in the delivery.
- `deliveryList` optional. The relayer will also deliver these (already existing) VAAs. This is the mechanism for re-delivery
- `relayParameters` information required to relay to the target env. Contains compute budget.
- `chainPayload` information which can be used for computation efficiency when relaying to other ecosystems.
- `nonce` optional. If included, only messages with this nonce will be relayed.
- `consistencyLevel` how long to wait before emitting the relay request.
- `msg.value` you must send enough native currency with this call to cover the compute budget specified in the relayer parameters.
- `targetChain`: chain ID of the chain this should be delivered to
- `targetAddress`: contract address to deliver to (_in Wormhole format_)
- `payload`: additional payload which will be included in the delivery
- `deliveryList` (_optional_): mechanism for re-delivery of already existing VAAs
- `relayParameters`: information required to relay to the target env. Contains compute budget
- `chainPayload`: information used for computation efficiency when relaying to other ecosystems
- `nonce` (_optional_): If included, only messages with this nonce will be relayed
- `consistencyLevel`: how long to wait before emitting the relay request
- `msg.value`: payment in native currency to relayer that must cover the compute budget specified in the relayer parameters
## Compute Budget
Part of the relay parameters is 'computeBudget'. This specifies the maximum amount of computation which can be spent executing delivery on the destination contract. This is effectively a 'gasLimit' in the EVM ecosystem, but due to the relayer network supporting blockchains which don't utilize the concept of gas, we instead need the more generalizable concept of 'computation budget'.
Part of the relay parameters is a 'computeBudget' which specifies the maximum amount of computation that can be spent executing delivery on the destination contract. This is effectively a 'gasLimit' in the EVM ecosystem, but due to the relayer network supporting blockchains that don't utilize the concept of gas, we use a more generalizable concept of 'computation budget'.
When requesting delivery, the caller must specify and pay for the compute budget upfront. Compute budget which is not utilized will be refunded on the target chain. If the compute budget is exhausted during execution of the delivery, a delivery failure occurs. When a delivery failure occurs, the computation budget from the source chain is not refunded, as the relayer used it to process the failed transaction.
When requesting delivery, the caller must specify and pay for the compute budget upfront. Compute budget which is not utilized will be refunded on the target chain. If the compute budget is exhausted during the execution of the delivery, a delivery failure occurs. When a delivery failure occurs, the computation budget from the source chain is not refunded, as the relayer used it to process the failed transaction.
The computation 'rate' is specified by the relayer module and is different for each blockchain. The quote provided by the relayer module contains not only the fee for the requested compute budget, but also the fixed overheads of the computation which is done by the relayer contract.
The computation 'rate' is specified by the relayer module and is different for each blockchain. The quote provided by the relayer module contains the fee for the requested compute budget AND the fixed overheads of the computation which is done by the relayer contract.
## Delivery Failures
'Delivery Failure' is a technical term in the case of the the relayer module. It does not mean 'something went wrong', but rather that the relayer attempted to deliver the VAA, and was unsuccessful. There are only 3 causes of a delivery failure.
'Delivery Failure' is a technical term in the case of the relayer module. It does not mean 'something went wrong', but rather that the relayer attempted to deliver the VAA, and was unsuccessful. There are only 3 causes of a delivery failure.
- The `wormholeReceiver` function is either missing or otherwise uncallable on the recipient contract.
- The `wormholeReceiver` function encountered an exception while processing.
- The `wormholeReceiver` function exhausted the gasLimit that was specified by the delivery requester.
- The `wormholeReceiver` function exhausted the computeBudget that was specified by the delivery requester.
All three of these scenarios are controllable by the integrator. In order to avoid delivery failures, the integrators should have a top-level try-catch, such that the wormholeReceiver never reverts, and should always request a worst-case compute budget, because excess budget will be refunded.
All three of these scenarios are controllable by the integrator. In order to avoid delivery failures, the integrators should have a top-level try-catch such that the wormholeReceiver never reverts, and should always request a worst-case compute budget since excess budget will be refunded.
## Delivery Retries

8
src/technical/relayer/genericRelayer.md
View File

@ -2,12 +2,16 @@
The defining characteristic of generic relayers is that they do not have any off-chain components for the xDapp developer. All aspects of this integration are on chain.
The implementation details vary by blockchain, and you should reference the `relayer module` documentation for each ecosystem. The general strategy is the same however.
The implementation details vary by blockchain so you should reference the `relayer module` documentation for each ecosystem. However, the general workflow is the same.
Developers are responsible for implementing a standardized interface which is part of the API agreement with the generic relayer network. This interface generally looks something like
```
receiveVAA(byte[] batchVAA)
wormholeReceiver(
bytes[] batchVAA,
sourceChain
sourceAddress
payload)
```
This is the entrypoint on your contract which will be called by the relayer.

2
src/technical/relayer/specializedRelayers.md
View File

@ -2,7 +2,7 @@
Rather than home-rolling a relayer, it's recommended that integrators start from the existing [Spy Relayer](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/relayer/spy_relayer) provided in the Wormhole Core Repository.
There's additionally an extensible relayer (called the [Plugin Relayer](https://github.com/wormhole-foundation/wormhole/tree/feat/plugin_relayer/relayer/plugin_relayer)) currently in development.
Additionally there's an extensible relayer (called the [Plugin Relayer](https://github.com/wormhole-foundation/wormhole/tree/feat/plugin_relayer/relayer/plugin_relayer)) currently in development.
<!-- To aid in the development of relayers, a extensible relayer implementation (called the [plugin relayer]()) has been provided in the Wormhole Core Repository.