From 0845b5326ec0c31d1bd36cfeef1f80c93e975dd1 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Fri, 23 Sep 2022 14:20:48 -0500 Subject: [PATCH 1/5] reference: line edits --- src/reference/glossary.md | 8 ++++---- src/reference/overview.md | 4 +--- src/reference/usefulLinks.md | 22 ++++++++++++---------- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/reference/glossary.md b/src/reference/glossary.md index cfb3a2e..4e353b6 100644 --- a/src/reference/glossary.md +++ b/src/reference/glossary.md @@ -1,8 +1,8 @@ # Glossary -In some instances, Wormhole uses general terms fo decentralized, cross-chain elements as branded verbiage. In most casese, the definition of the general term does not differ from Wormhole's definition though Wormhole's definitions may be more narrow than general interpretations. +_Disclaimer: In some instances, Wormhole uses general terms for decentralized, cross-chain elements as branded verbiage. In most casese, the definition of the general term does not differ from Wormhole's definition though Wormhole's definitions may be more narrow than general interpretations._ -**Guardian** - One of the 19 validators in the Guardian Network that Contributes to the VAA multisig. +**Guardian** - One of the 19 validators in the Guardian Network that contributes to the VAA multisig. [**Guardian Network**](../wormhole/5_guardianNetwork.md) - Validators that exist in their own p2p network that serve as Wormhole's oracle by observing activity on-chain and generating signed messages attesting to that activity. @@ -12,9 +12,9 @@ In some instances, Wormhole uses general terms fo decentralized, cross-chain ele [**Wormchain**](../wormhole/8_wormchain.md) - A purpose-built cosmos blockchain which aids the Guardian Network and allows for formal interaction with the Guardians. -[**xAssets**](../dapps/3_xdataxassets.md) - Chain-and-path agnostic token that exists on a layer outside the blockchain ecosystem, which can be used to conduct transactions on any blockchain. There are currently two implemented modules: (1) [Token Bridge Module](../technical/evm/xassetLayer.md) and (2) [NFT Bridge Module](../technical/evm/nftLayer.md) +[**xAssets**](../dapps/3_xdataxassets.md) - Chain-and-path agnostic token that exists on a layer outside the blockchain ecosystem, which can be used to conduct transactions on any blockchain. There are currently two implemented modules: (1) [Token Bridge Module](../technical/evm/tokenLayer.md) and (2) [NFT Bridge Module](../technical/evm/nftLayer.md) -**xChain** - Term that referrs to the full range of cross-blockchain interoperability. +**xChain** - Term that refers to the full range of cross-blockchain interoperability. [**xDapp**](../dapps/4_whatIsanXdapp.md) - Decentralized application that enables users to create and/or use xData. diff --git a/src/reference/overview.md b/src/reference/overview.md index 83ea2e2..2c93451 100644 --- a/src/reference/overview.md +++ b/src/reference/overview.md @@ -3,8 +3,6 @@ Here is a collection of other resources and reference sources which you're likely to find helpful. - [Glossary & Terms](./glossary.md) -- [Tools & Helpful Links](./tools.md) -- [Github](./github.md) +- [Tools & Helpful Links](./usefulLinks.md) - [Contract Addresses & Environment Information](./contracts.md) - [RPC Info](./rpcnodes.md) -- [Block Finality Suggestions](./finality.md) diff --git a/src/reference/usefulLinks.md b/src/reference/usefulLinks.md index ef4f913..e8348c9 100644 --- a/src/reference/usefulLinks.md +++ b/src/reference/usefulLinks.md @@ -1,30 +1,32 @@ -# Useful Links +# Tools and Useful Links -Below are a variety of useful links to tools and information in the Wormhole ecosystem that can help you develop xDapps. +Below are a variety of tools and information in the Wormhole ecosystem that can help you develop xDapps. -### Design Documents +### [Design Documents](https://github.com/certusone/wormhole/tree/dev.v2/whitepapers) -Wormhole's component design specifications can be found [here](https://github.com/certusone/wormhole/tree/dev.v2/whitepapers). These outline the reasoning behind design decisions with added technical depth. +Wormhole's component design specifications outline the reasoning behind design decisions with added technical depth. ### Testnet -Wormhole has deployed Core Bridge, Token Bridge and NFT Bridge contracts on various testnets of the chains connected by Wormhole. You can see the deployed addresses [here](./contracts.md). There's only a single Guardian that oversees the testnets, so you might get a higher rate of missed VAAs than you would on mainnet. +Wormhole has deployed Core Bridge, Token Bridge and NFT Bridge contracts on various testnets of the chains connected by Wormhole. You can see the deployed addresses [here](./contracts.md). -### Testnet Bridge UI +_Note: There's only a single Guardian that oversees the testnets, so you might experience a higher rate of missed VAAs than you would on mainnet._ -If you'd like to try out bridging tokens on testnet, there's a UI you can use to attest and transfer tokens for testnet, hosted [here](https://wormhole-foundation.github.io/example-token-bridge-ui/#/transfer). +### [Testnet Bridge UI](https://wormhole-foundation.github.io/example-token-bridge-ui/#/transfer) + +An example UI provided to test out attesting and bridging tokens on testnet. ### Tilt -Tilt is a Kubernetes-based tool that runs a copy of every chain along side a Guardian node to create a simulated testing environment. To set it up and test against it, start [here](../development/tilt/overview.md). +Tilt is a Kubernetes-based tool that runs a copy of every chain along side a Guardian node to create a simulated testing environment. Details on how to set it up and test against it is [here](../development/tilt/overview.md). ### Wormhole Core Repository The Wormhole core repository can be found at [https://github.com/wormhole-foundation/wormhole](https://github.com/wormhole-foundation/wormhole). -### Wormhole Explorer +### [Wormhole Explorer](https://wormholenetwork.com/en/explorer) -[Wormhole Explorer](https://wormholenetwork.com/en/explorer) is a tool that will help you parse VAAs after they've been picked up the Guardian network. +Tool to observe all Wormhole activity and can help you parse VAAs after they've been picked up the Guardian network. ### Wormhole SDK From 4a9c474bfb99f57d971fce88d3457dc6e27363a8 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Fri, 23 Sep 2022 14:21:04 -0500 Subject: [PATCH 2/5] relayer: line edits --- src/technical/evm/relayer.md | 58 ++++++++++---------- src/technical/relayer/genericRelayer.md | 8 ++- src/technical/relayer/specializedRelayers.md | 2 +- 3 files changed, 36 insertions(+), 32 deletions(-) diff --git a/src/technical/evm/relayer.md b/src/technical/evm/relayer.md index ae5536b..892c77a 100644 --- a/src/technical/evm/relayer.md +++ b/src/technical/evm/relayer.md @@ -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 diff --git a/src/technical/relayer/genericRelayer.md b/src/technical/relayer/genericRelayer.md index 110051d..a57f480 100644 --- a/src/technical/relayer/genericRelayer.md +++ b/src/technical/relayer/genericRelayer.md @@ -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. diff --git a/src/technical/relayer/specializedRelayers.md b/src/technical/relayer/specializedRelayers.md index 118ae7f..4049dbe 100644 --- a/src/technical/relayer/specializedRelayers.md +++ b/src/technical/relayer/specializedRelayers.md @@ -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.