relayer module info

src/SUMMARY.md

@@ -1,6 +1,6 @@
 # Summary
 
-- [Introduction](./introduction/introduction.md)
+[Introduction](./introduction/introduction.md)
 
 ---
 
@@ -51,14 +51,13 @@
     - [Core Layer](./technical/evm/coreLayer.md)
     - [Token Bridge Module](./technical/evm/tokenLayer.md)
     - [NFT Bridge Module](./technical/evm/nftLayer.md)
+    - [Relayer Module](./technical/evm/relayer.md)
     - [Best Practices](./technical/evm/bestPractices.md)
-    <!-- - [Relayer Module](./technical/evm/relayer.md) -->
   - [Solana](./technical/solana/overview.md)
   - [Cosmos](./technical/cosmos/overview.md)
   - [Algorand](./technical/algorand/overview.md)
   - [Near](./technical/near/overview.md)
   - [Aptos](./technical/aptos/overview.md)
-  - [Sui]()
 
 - [Relayers](./technical/relayer/overview.md)
 

src/technical/evm/relayer.md

@@ -1 +1,89 @@
 # Relayer Module
+
+Note: 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.
+
+2. The integrator must request delivery to the target chain via 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.
+
+```
+function wormholeReceiver(
+    bytes[] memory vaas,
+    uint16 sourceChain,
+    bytes32 sourceAddress,
+    bytes memory payload
+)
+```
+
+This is the function which will be invoked by the relayer module to deliver messages.
+
+- `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.
+
+There are only 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.
+
+## Sending Messages
+
+In order to send a message to another contract, you must call `requestDelivery(DeliveryInstructions instructions)`. There are a few different things you can accomplish with this call.
+
+First let's lay out the DeliveryInstructions object, which is part of the relayer module structs.
+
+```
+struct DeliveryParameters {
+    uint16 targetChain;
+    bytes32 targetAddress;
+    bytes payload;
+    VAAId[] deliveryList;
+    bytes relayParameters;
+    bytes chainPayload;
+    uint32 nonce;
+    uint8 consistencyLevel;
+}
+```
+
+- `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.
+
+## 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'.
+
+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.
+
+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.
+
+## 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.
+
+- 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.
+
+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.
+
+## Delivery Retries
+
+In the unfortunate scenario of a delivery failure, the VAAs can be re-delivered by requesting their delivery a second time. To accomplish this, simply list their VAA IDs in the `deliveryList` in the call.
+
+**More info and features to come. This module is still in development.**