From 12a227e265d2920e407c6109f560d3f4cc53c09f Mon Sep 17 00:00:00 2001 From: Ilaria Enache Date: Tue, 30 Jul 2024 10:51:09 +0200 Subject: [PATCH 01/18] relayers page setup --- learn/infrastructure/.pages | 1 + learn/infrastructure/relayer.md | 15 +++++++ learn/infrastructure/spy.md | 70 --------------------------------- 3 files changed, 16 insertions(+), 70 deletions(-) create mode 100644 learn/infrastructure/relayer.md delete mode 100644 learn/infrastructure/spy.md diff --git a/learn/infrastructure/.pages b/learn/infrastructure/.pages index da6851651..9f6676578 100644 --- a/learn/infrastructure/.pages +++ b/learn/infrastructure/.pages @@ -4,3 +4,4 @@ nav: - 'VAAs': 'vaas.md' - 'Guardians': 'guardians.md' - 'SPY': 'spy.md' + - 'Relayers': 'relayer.md' diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md new file mode 100644 index 000000000..259b3d9b6 --- /dev/null +++ b/learn/infrastructure/relayer.md @@ -0,0 +1,15 @@ +--- +title: Relayer +description: +--- + + + +# Relayers \ No newline at end of file diff --git a/learn/infrastructure/spy.md b/learn/infrastructure/spy.md deleted file mode 100644 index 097cd99a9..000000000 --- a/learn/infrastructure/spy.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: SPY -description: ---- - -# SPY - -In the wormhole context, a _spy_ is a daemon that subscribes to the gossiped messages in the Guardian Network. - -The messages available over gossip are things like - -- [VAAs](#){target=\_blank} -- [Observations](#){target=\_blank} -- Guardian Heartbeats - -The source for the Spy is available on [Github](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/spy/spy.go){target=\_blank} - -!!! note - The Spy has no persistence layer built in, so typically, it is paired with something like Redis or an SQL database to record relevant messages - -## Use - -To start a Spy locally, run the following docker command. - -=== "Testnet" - - ```sh - docker run --platform=linux/amd64 \ - -p 7073:7073 \ - --entrypoint /guardiand ghcr.io/wormhole-foundation/guardiand:latest \ - spy \ - --nodeKey /node.key \ - --spyRPC "[::]:7073" \ - --env testnet - ``` - Optionally, add the flags to skip any VAAs with invalid signatures - ```sh - --ethRPC https://sepolia.drpc.org/ - --ethContract 0x4a8bc80Ed5a4067f1CCf107057b8270E0cC11A78 - ``` - -=== "Mainnet" - - ```sh - docker run --platform=linux/amd64 \ - -p 7073:7073 \ - --entrypoint /guardiand ghcr.io/wormhole-foundation/guardiand:latest \ - spy \ - --nodeKey /node.key \ - --spyRPC "[::]:7073" \ - --env mainnet - ``` - Optionally, add the flags to skip any VAAs with invalid signatures - ```sh - --ethRPC https://eth.drpc.org - --ethContract 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B - ``` - -Once running, a [gRPC](https://grpc.io/){target=\_blank} client (i.e. your program) can subscribe to a filtered stream of messages. - -To generate a client for the gRPC service use [this proto spec file](https://github.com/wormhole-foundation/wormhole/blob/main/proto/spy/v1/spy.proto){target=\_blank}. - -!!! note - If using JavaScript/TypeScript, the [Spydk](https://www.npmjs.com/package/@certusone/wormhole-spydk){target=\_blank} makes setting up a client easier. - -## See Also - -The [Pyth Beacon](https://github.com/pyth-network/beacon){target=\_blank} provides an alternate Spy implementation that is highly available for improved performance and reliability. - -The [relayer engine](https://github.com/wormhole-foundation/relayer-engine){target=\_blank} implements a client and persistence layer for messages received from a Spy subscription. \ No newline at end of file From f98adbdba0b170884fc32a5a5010a2daede79624 Mon Sep 17 00:00:00 2001 From: Ilaria Enache Date: Tue, 30 Jul 2024 11:20:32 +0200 Subject: [PATCH 02/18] relayers page content --- learn/infrastructure/relayer.md | 114 +++++++++++++++++++++++++++++++- 1 file changed, 112 insertions(+), 2 deletions(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 259b3d9b6..69ddab857 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -1,5 +1,5 @@ --- -title: Relayer +title: Relayers description: --- @@ -12,4 +12,114 @@ description: ``` --> -# Relayers \ No newline at end of file +# Relayers + +This documentation provides a comprehensive guide to Relayers within the Wormhole network, describing their role, types, and benefits in facilitating cross-chain processes. + +Relayers in the Wormhole context are processes that deliver Verifiable Action Approvals ([VAAs](#){target=\_blank}) to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only liveness, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome. + +There are three primary types of relayers discussed: + +- **Client-side Relaying** - a cost-efficient, no-backend-infrastructure approach relying on user-facing front ends. It provides a simple solution, although it can complicate the user experience due to the manual steps involved +- **Specialized Relayers** - they are backend components that handle parts of the cross-chain process, offering a smoother user experience and allowing off-chain calculations to reduce gas costs. These relayers could operate through direct listening to the Guardian Network (Spy Relaying) or by providing a REST endpoint to accept VAAs to be relayed (REST Relaying) +- **Standard Relayers** - a decentralized relayer network that can deliver arbitrary VAAs, reducing the developer's need to develop, host, or maintain relayers. However, they require all calculations to be done on-chain and might be less gas-efficient + +## Fundamentals + +This section highlights the crucial principles underpinning the operation and handling of relayers within the Wormhole network. + +Relayers are fundamentally untrusted entities within the network. This means that while they don't require your trust, they shouldn't be trusted implicitly. They function as delivery mechanisms, transporting Verifiable Action Approvals (VAAs) from their source to their destination. + +Key characteristics of VAAs include: + +- Public emission from the Guardian Network +- Authentication through signatures from the Guardian Network +- Verifiability by any entity or any Wormhole Core Contract +- As a result of these characteristics, anyone can pick up a VAA and deliver it anywhere, but no one can alter the VAA content without invalidating the signatures + +When designing contracts, it's crucial to only trust information contained within your contract or a VAA. Relying on information from a relayer could expose you to untrusted input attacks. + +Advanced strategies can involve having relayers perform untrusted off-chain computation, which is passed into the destination contract. These strategies can optimize gas costs but can also create attack vectors if not used correctly. + +In summary, the design of a relayer should ensure there's a single, deterministic way that messages in your protocol can be processed. In an optimally designed protocol, relayers should have a 'correct' implementation, mirroring "crank turner" processes used elsewhere in blockchain. + +## Client-side Relaying + +Client-side relaying relies on user-facing front ends, such as a webpage or a wallet, to carry out the complete cross-chain process. + +### Key Features + +- **Cost-Efficiency** - Users only pay for the transaction fee for the second transaction, eliminating any additional costs. +- **No Backend Infrastructure** - The process is completely client-based, eliminating the need for a backend relaying infrastructure. + +### Implementation + +Users themselves carry out the three steps of the cross-chain process: + +1. Perform an action on chain A +2. Retrieve the resulting VAA from the Guardian Network +3. Perform an action on chain B using the VAA + +### Considerations + +!!! note + Though simple, this type of relaying is generally not recommended if your aim is a highly-polished user experience. It can, however, be useful for getting a Minimum Viable Product (MVP) up and running. + +- Users must sign all required transactions with their own wallet +- Users must have funds to pay the transaction fees on every chain involved +- The user experience may be cumbersome due to the manual steps involved + +## Specialized Relayers + +Specialized relayers are purpose-built components within the Wormhole protocol, designed to relay messages for specific applications. They are capable of performing off-chain computations and can be customized to suit a variety of use-cases. + +### Key Features + +- **Optimization** - capable of performing untrusted off-chain computations which can optimize gas costs +- **Customizability** - allows for specific strategies like batching, conditional delivery, multi-chain deliveries, and more +- **Incentive Structure** - developers have the freedom to design an incentive structure suitable for their application +- **Enhanced UX** - the ability to perform steps 2 and 3 of the cross-chain process on behalf of the user can simplify the user experience + +### Implementation + +!!! note + To make the development of specialized relayers easier, a plugin relayer is available in the [main Wormhole repository](#){target=\_blank}. This sets up the basic infrastructure for relaying, allowing developers to focus on implementing the specific logic for their application. + +There are two main methods of setting up a specialized relayer: + +- **Spy Relaying** - involves listening directly to the Guardian Network via a spy +- **REST Relaying** - provides a REST endpoint to accept a VAA that should be relayed + +### Considerations + +Remember, despite their name, specialized relayers are still considered untrusted. VAAs are public and can be submitted by anyone, so developers should not rely on off-chain relayers to perform any computation which is considered "trusted". + +- Development work and hosting of relayers are required +- The fee-modeling can become complex, as relayers are responsible for paying target chain fees +- Relayers are responsible for liveness, adding an additional dependency for the cross chain application + +## Standard Relayers + +Standard relayers are a component of a decentralized network in the Wormhole protocol, facilitating the delivery of Verifiable Action Approvals (VAAs) to recipient contracts compatible with the standard relayer API. + +### Key Features + +- **Lower Operational Costs** - no need to develop, host, or maintain individual relayers +- **Simplified Integration** - because there is no need to run a relayer, integration is as simple as calling a function and implementing an interface + +### Implementation + +The standard relayer integration involves two key steps: + +- **Delivery Request** - request delivery from the Wormhole Relay Ecosystem Contract +- **Relay Reception** - implement a [receiveWormholeMessages](#){target=\_blank} function within their contracts. This function is invoked upon successful relay of the VAA + +### Considerations + +!!! note + Developers should note that the choice of relayers depends on the specific requirements and constraints of their project. Standard relayers offer simplicity and convenience but might limit customization and optimization opportunities compared to specialized relayers. + +- All computations are performed on-chain +- Potentially less gas-efficient compared to specialized relayers +- Optimization features like conditional delivery, batching, off-chain calculations might be restricted +- Support may not be available for all chains \ No newline at end of file From 3b37b0a303ac38f2f499b73431c8e5ae9963383a Mon Sep 17 00:00:00 2001 From: Ilaria Enache Date: Tue, 30 Jul 2024 16:48:48 +0200 Subject: [PATCH 03/18] grammarly check and minor fixes --- learn/infrastructure/relayer.md | 51 ++++++++++++++------------------- 1 file changed, 21 insertions(+), 30 deletions(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 69ddab857..a9dfb48c6 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -1,17 +1,8 @@ --- title: Relayers -description: +description: Discover the role and types of relayers in the Wormhole network, including client-side, specialized, and standard relayers, facilitating secure cross-chain communication. --- - - # Relayers This documentation provides a comprehensive guide to Relayers within the Wormhole network, describing their role, types, and benefits in facilitating cross-chain processes. @@ -21,7 +12,7 @@ Relayers in the Wormhole context are processes that deliver Verifiable Action Ap There are three primary types of relayers discussed: - **Client-side Relaying** - a cost-efficient, no-backend-infrastructure approach relying on user-facing front ends. It provides a simple solution, although it can complicate the user experience due to the manual steps involved -- **Specialized Relayers** - they are backend components that handle parts of the cross-chain process, offering a smoother user experience and allowing off-chain calculations to reduce gas costs. These relayers could operate through direct listening to the Guardian Network (Spy Relaying) or by providing a REST endpoint to accept VAAs to be relayed (REST Relaying) +- **Specialized Relayers** - backend components that handle parts of the cross-chain process, offering a smoother user experience and allowing off-chain calculations to reduce gas costs. These relayers could operate through direct listening to the Guardian Network (Spy Relaying) or by providing a REST endpoint to accept VAAs to be relayed (REST Relaying) - **Standard Relayers** - a decentralized relayer network that can deliver arbitrary VAAs, reducing the developer's need to develop, host, or maintain relayers. However, they require all calculations to be done on-chain and might be less gas-efficient ## Fundamentals @@ -39,20 +30,20 @@ Key characteristics of VAAs include: When designing contracts, it's crucial to only trust information contained within your contract or a VAA. Relying on information from a relayer could expose you to untrusted input attacks. -Advanced strategies can involve having relayers perform untrusted off-chain computation, which is passed into the destination contract. These strategies can optimize gas costs but can also create attack vectors if not used correctly. +Advanced strategies can involve relayers performing untrusted off-chain computation passed into the destination contract. These strategies can optimize gas costs but also create attack vectors if not used correctly. -In summary, the design of a relayer should ensure there's a single, deterministic way that messages in your protocol can be processed. In an optimally designed protocol, relayers should have a 'correct' implementation, mirroring "crank turner" processes used elsewhere in blockchain. +In summary, the design of a relayer should ensure that there's a single, deterministic way to process messages in your protocol. In an optimally designed protocol, relayers should have a 'correct' implementation, mirroring "crank turner" processes used elsewhere in blockchain. ## Client-side Relaying -Client-side relaying relies on user-facing front ends, such as a webpage or a wallet, to carry out the complete cross-chain process. +Client-side relaying relies on user-facing front ends, such as a webpage or a wallet, to complete the cross-chain process. -### Key Features +**Key Features** -- **Cost-Efficiency** - Users only pay for the transaction fee for the second transaction, eliminating any additional costs. -- **No Backend Infrastructure** - The process is completely client-based, eliminating the need for a backend relaying infrastructure. +- **Cost-Efficiency** - users only pay the transaction fee for the second transaction, eliminating any additional costs +- **No Backend Infrastructure** - the process is completely client-based, eliminating the need for a backend relaying infrastructure -### Implementation +**Implementation** Users themselves carry out the three steps of the cross-chain process: @@ -60,10 +51,10 @@ Users themselves carry out the three steps of the cross-chain process: 2. Retrieve the resulting VAA from the Guardian Network 3. Perform an action on chain B using the VAA -### Considerations +**Considerations** !!! note - Though simple, this type of relaying is generally not recommended if your aim is a highly-polished user experience. It can, however, be useful for getting a Minimum Viable Product (MVP) up and running. + Though simple, this type of relaying is generally not recommended if your aim is a highly polished user experience. It can, however, be useful for getting a Minimum Viable Product (MVP) up and running. - Users must sign all required transactions with their own wallet - Users must have funds to pay the transaction fees on every chain involved @@ -71,16 +62,16 @@ Users themselves carry out the three steps of the cross-chain process: ## Specialized Relayers -Specialized relayers are purpose-built components within the Wormhole protocol, designed to relay messages for specific applications. They are capable of performing off-chain computations and can be customized to suit a variety of use-cases. +Specialized relayers are purpose-built components within the Wormhole protocol, designed to relay messages for specific applications. They are capable of performing off-chain computations and can be customized to suit a variety of use cases. -### Key Features +**Key Features** - **Optimization** - capable of performing untrusted off-chain computations which can optimize gas costs - **Customizability** - allows for specific strategies like batching, conditional delivery, multi-chain deliveries, and more - **Incentive Structure** - developers have the freedom to design an incentive structure suitable for their application - **Enhanced UX** - the ability to perform steps 2 and 3 of the cross-chain process on behalf of the user can simplify the user experience -### Implementation +**Implementation** !!! note To make the development of specialized relayers easier, a plugin relayer is available in the [main Wormhole repository](#){target=\_blank}. This sets up the basic infrastructure for relaying, allowing developers to focus on implementing the specific logic for their application. @@ -90,34 +81,34 @@ There are two main methods of setting up a specialized relayer: - **Spy Relaying** - involves listening directly to the Guardian Network via a spy - **REST Relaying** - provides a REST endpoint to accept a VAA that should be relayed -### Considerations +**Considerations** -Remember, despite their name, specialized relayers are still considered untrusted. VAAs are public and can be submitted by anyone, so developers should not rely on off-chain relayers to perform any computation which is considered "trusted". +Remember, despite their name, specialized relayers still need to be considered untrusted. VAAs are public and can be submitted by anyone, so developers should not rely on off-chain relayers to perform any computation considered "trusted." - Development work and hosting of relayers are required - The fee-modeling can become complex, as relayers are responsible for paying target chain fees -- Relayers are responsible for liveness, adding an additional dependency for the cross chain application +- Relayers are responsible for liveness, adding dependency for the cross-chain application ## Standard Relayers Standard relayers are a component of a decentralized network in the Wormhole protocol, facilitating the delivery of Verifiable Action Approvals (VAAs) to recipient contracts compatible with the standard relayer API. -### Key Features +**Key Features** - **Lower Operational Costs** - no need to develop, host, or maintain individual relayers - **Simplified Integration** - because there is no need to run a relayer, integration is as simple as calling a function and implementing an interface -### Implementation +**Implementation** The standard relayer integration involves two key steps: - **Delivery Request** - request delivery from the Wormhole Relay Ecosystem Contract - **Relay Reception** - implement a [receiveWormholeMessages](#){target=\_blank} function within their contracts. This function is invoked upon successful relay of the VAA -### Considerations +**Considerations** !!! note - Developers should note that the choice of relayers depends on the specific requirements and constraints of their project. Standard relayers offer simplicity and convenience but might limit customization and optimization opportunities compared to specialized relayers. + Developers should note that the choice of relayers depends their project's specific requirements and constraints. Standard relayers offer simplicity and convenience but limit customization and optimization opportunities compared to specialized relayers. - All computations are performed on-chain - Potentially less gas-efficient compared to specialized relayers From 0d94c1c29e28bdcf72b1f88501399f3856d192fc Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Tue, 30 Jul 2024 19:40:12 +0200 Subject: [PATCH 04/18] Update learn/infrastructure/relayer.md Co-authored-by: Dawn Kelly <83190195+dawnkelly09@users.noreply.github.com> --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index a9dfb48c6..3fbea8cb8 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -103,7 +103,7 @@ Standard relayers are a component of a decentralized network in the Wormhole pro The standard relayer integration involves two key steps: - **Delivery Request** - request delivery from the Wormhole Relay Ecosystem Contract -- **Relay Reception** - implement a [receiveWormholeMessages](#){target=\_blank} function within their contracts. This function is invoked upon successful relay of the VAA +- **Relay Reception** - implement a [`receiveWormholeMessages`](#){target=\_blank} function within their contracts. This function is invoked upon successful relay of the VAA **Considerations** From 6f2b6af1e44d515c443dc84eba435c40a5a3e12b Mon Sep 17 00:00:00 2001 From: Ilaria Enache Date: Tue, 30 Jul 2024 19:42:12 +0200 Subject: [PATCH 05/18] shortened meta description --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 3fbea8cb8..45aa6109d 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -1,6 +1,6 @@ --- title: Relayers -description: Discover the role and types of relayers in the Wormhole network, including client-side, specialized, and standard relayers, facilitating secure cross-chain communication. +description: Discover the role of relayers in the Wormhole network, including client-side, specialized, and standard types, for secure cross-chain communication. --- # Relayers From 4d0b6a7d694b0f9aee1c678abe97d3ade7b53085 Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Wed, 31 Jul 2024 21:05:42 +0200 Subject: [PATCH 06/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 45aa6109d..e51dfb57f 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -5,7 +5,7 @@ description: Discover the role of relayers in the Wormhole network, including cl # Relayers -This documentation provides a comprehensive guide to Relayers within the Wormhole network, describing their role, types, and benefits in facilitating cross-chain processes. +This documentation provides a comprehensive guide to relayers within the Wormhole network, describing their role, types, and benefits in facilitating cross-chain processes. Relayers in the Wormhole context are processes that deliver Verifiable Action Approvals ([VAAs](#){target=\_blank}) to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only liveness, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome. From 00a6efdf83459dd20db94aba3e5e977ca5bb83df Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Wed, 31 Jul 2024 21:05:50 +0200 Subject: [PATCH 07/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index e51dfb57f..34bc78859 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -34,7 +34,7 @@ Advanced strategies can involve relayers performing untrusted off-chain computat In summary, the design of a relayer should ensure that there's a single, deterministic way to process messages in your protocol. In an optimally designed protocol, relayers should have a 'correct' implementation, mirroring "crank turner" processes used elsewhere in blockchain. -## Client-side Relaying +## Client-Side Relaying Client-side relaying relies on user-facing front ends, such as a webpage or a wallet, to complete the cross-chain process. From 29730ef53c537571a79dc7f940509fe531432651 Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Wed, 31 Jul 2024 21:05:57 +0200 Subject: [PATCH 08/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 34bc78859..5353ad3bc 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -78,7 +78,7 @@ Specialized relayers are purpose-built components within the Wormhole protocol, There are two main methods of setting up a specialized relayer: -- **Spy Relaying** - involves listening directly to the Guardian Network via a spy +- **Spy Relaying** - involves listening directly to the Guardian Network via a Spy - **REST Relaying** - provides a REST endpoint to accept a VAA that should be relayed **Considerations** From c127a944fa46a2680ce7e49022acd9bc9602ff50 Mon Sep 17 00:00:00 2001 From: Ilaria Enache Date: Thu, 1 Aug 2024 10:26:21 +0200 Subject: [PATCH 09/18] feedback fixes --- learn/infrastructure/relayer.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 5353ad3bc..5cc3ed33b 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -7,19 +7,19 @@ description: Discover the role of relayers in the Wormhole network, including cl This documentation provides a comprehensive guide to relayers within the Wormhole network, describing their role, types, and benefits in facilitating cross-chain processes. -Relayers in the Wormhole context are processes that deliver Verifiable Action Approvals ([VAAs](#){target=\_blank}) to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only liveness, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome. +Relayers in the Wormhole context are processes that deliver [VAAs](#){target=\_blank} to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only liveness, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome. There are three primary types of relayers discussed: -- **Client-side Relaying** - a cost-efficient, no-backend-infrastructure approach relying on user-facing front ends. It provides a simple solution, although it can complicate the user experience due to the manual steps involved -- **Specialized Relayers** - backend components that handle parts of the cross-chain process, offering a smoother user experience and allowing off-chain calculations to reduce gas costs. These relayers could operate through direct listening to the Guardian Network (Spy Relaying) or by providing a REST endpoint to accept VAAs to be relayed (REST Relaying) +- **Client-side relaying** - a cost-efficient, no-backend-infrastructure approach relying on user-facing front ends. It provides a simple solution, although it can complicate the user experience due to the manual steps involved +- **Specialized relayers** - backend components that handle parts of the cross-chain process, offering a smoother user experience and allowing off-chain calculations to reduce gas costs. These relayers could operate through direct listening to the Guardian Network (Spy relaying) or by providing a REST endpoint to accept VAAs to be relayed (REST relaying) - **Standard Relayers** - a decentralized relayer network that can deliver arbitrary VAAs, reducing the developer's need to develop, host, or maintain relayers. However, they require all calculations to be done on-chain and might be less gas-efficient ## Fundamentals This section highlights the crucial principles underpinning the operation and handling of relayers within the Wormhole network. -Relayers are fundamentally untrusted entities within the network. This means that while they don't require your trust, they shouldn't be trusted implicitly. They function as delivery mechanisms, transporting Verifiable Action Approvals (VAAs) from their source to their destination. +Relayers are fundamentally untrusted entities within the network. This means that while they don't require your trust, they shouldn't be trusted implicitly. They function as delivery mechanisms, transporting VAAs from their source to their destination. Key characteristics of VAAs include: @@ -32,9 +32,9 @@ When designing contracts, it's crucial to only trust information contained withi Advanced strategies can involve relayers performing untrusted off-chain computation passed into the destination contract. These strategies can optimize gas costs but also create attack vectors if not used correctly. -In summary, the design of a relayer should ensure that there's a single, deterministic way to process messages in your protocol. In an optimally designed protocol, relayers should have a 'correct' implementation, mirroring "crank turner" processes used elsewhere in blockchain. +In summary, the design of a relayer should ensure that there's a single, deterministic way to process messages in your protocol. In an optimally designed protocol, relayers should have a "correct" implementation, mirroring "crank turner" processes used elsewhere in blockchain. -## Client-Side Relaying +## Client-Side relaying Client-side relaying relies on user-facing front ends, such as a webpage or a wallet, to complete the cross-chain process. @@ -69,7 +69,7 @@ Specialized relayers are purpose-built components within the Wormhole protocol, - **Optimization** - capable of performing untrusted off-chain computations which can optimize gas costs - **Customizability** - allows for specific strategies like batching, conditional delivery, multi-chain deliveries, and more - **Incentive Structure** - developers have the freedom to design an incentive structure suitable for their application -- **Enhanced UX** - the ability to perform steps 2 and 3 of the cross-chain process on behalf of the user can simplify the user experience +- **Enhanced UX** - the ability to retrieve a VAA from the Guardian Network and perform an action on the target chain using the VAA on behalf of the user can simplify the user experience **Implementation** @@ -78,8 +78,8 @@ Specialized relayers are purpose-built components within the Wormhole protocol, There are two main methods of setting up a specialized relayer: -- **Spy Relaying** - involves listening directly to the Guardian Network via a Spy -- **REST Relaying** - provides a REST endpoint to accept a VAA that should be relayed +- **Spy relaying** - involves listening directly to the Guardian Network via a Spy +- **REST relaying** - provides a REST endpoint to accept a VAA that should be relayed **Considerations** @@ -91,7 +91,7 @@ Remember, despite their name, specialized relayers still need to be considered u ## Standard Relayers -Standard relayers are a component of a decentralized network in the Wormhole protocol, facilitating the delivery of Verifiable Action Approvals (VAAs) to recipient contracts compatible with the standard relayer API. +Standard relayers are a component of a decentralized network in the Wormhole protocol, facilitating the delivery of VAAs to recipient contracts compatible with the standard relayer API. **Key Features** From c756d4801f972cf9bada6ea4cf7a07e183aab932 Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Thu, 1 Aug 2024 18:52:01 +0200 Subject: [PATCH 10/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 5cc3ed33b..5276d2503 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -7,7 +7,7 @@ description: Discover the role of relayers in the Wormhole network, including cl This documentation provides a comprehensive guide to relayers within the Wormhole network, describing their role, types, and benefits in facilitating cross-chain processes. -Relayers in the Wormhole context are processes that deliver [VAAs](#){target=\_blank} to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only liveness, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome. +Relayers in the Wormhole context are processes that deliver [Verified Action Approvals (VAAs)](#){target=\_blank} to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only liveness, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome. There are three primary types of relayers discussed: From ac3d0702e879af370632a8afc851b15c3eba8bdc Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Thu, 1 Aug 2024 18:52:09 +0200 Subject: [PATCH 11/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 5276d2503..89f7689c8 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -13,7 +13,7 @@ There are three primary types of relayers discussed: - **Client-side relaying** - a cost-efficient, no-backend-infrastructure approach relying on user-facing front ends. It provides a simple solution, although it can complicate the user experience due to the manual steps involved - **Specialized relayers** - backend components that handle parts of the cross-chain process, offering a smoother user experience and allowing off-chain calculations to reduce gas costs. These relayers could operate through direct listening to the Guardian Network (Spy relaying) or by providing a REST endpoint to accept VAAs to be relayed (REST relaying) -- **Standard Relayers** - a decentralized relayer network that can deliver arbitrary VAAs, reducing the developer's need to develop, host, or maintain relayers. However, they require all calculations to be done on-chain and might be less gas-efficient +- **Standard relayers** - a decentralized relayer network that can deliver arbitrary VAAs, reducing the developer's need to develop, host, or maintain relayers. However, they require all calculations to be done on-chain and might be less gas-efficient ## Fundamentals From 4c41feb15cf0ce7e9548d29e1dcf854979991ccb Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Thu, 1 Aug 2024 18:53:22 +0200 Subject: [PATCH 12/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 89f7689c8..72941590b 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -68,7 +68,7 @@ Specialized relayers are purpose-built components within the Wormhole protocol, - **Optimization** - capable of performing untrusted off-chain computations which can optimize gas costs - **Customizability** - allows for specific strategies like batching, conditional delivery, multi-chain deliveries, and more -- **Incentive Structure** - developers have the freedom to design an incentive structure suitable for their application +- **Incentive structure** - developers have the freedom to design an incentive structure suitable for their application - **Enhanced UX** - the ability to retrieve a VAA from the Guardian Network and perform an action on the target chain using the VAA on behalf of the user can simplify the user experience **Implementation** From 78dc3be141de88309103e45bf5b9806ed034bedb Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Thu, 1 Aug 2024 18:53:27 +0200 Subject: [PATCH 13/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 72941590b..000e3e191 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -95,8 +95,8 @@ Standard relayers are a component of a decentralized network in the Wormhole pro **Key Features** -- **Lower Operational Costs** - no need to develop, host, or maintain individual relayers -- **Simplified Integration** - because there is no need to run a relayer, integration is as simple as calling a function and implementing an interface +- **Lower operational costs** - no need to develop, host, or maintain individual relayers +- **Simplified integration** - because there is no need to run a relayer, integration is as simple as calling a function and implementing an interface **Implementation** From fbc7c459369827d2c410efba6bb410dcfc455f0a Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Thu, 1 Aug 2024 18:53:32 +0200 Subject: [PATCH 14/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 000e3e191..9f79b21cc 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -102,8 +102,8 @@ Standard relayers are a component of a decentralized network in the Wormhole pro The standard relayer integration involves two key steps: -- **Delivery Request** - request delivery from the Wormhole Relay Ecosystem Contract -- **Relay Reception** - implement a [`receiveWormholeMessages`](#){target=\_blank} function within their contracts. This function is invoked upon successful relay of the VAA +- **Delivery request** - request delivery from the Wormhole Relay Ecosystem Contract +- **Relay reception** - implement a [`receiveWormholeMessages`](#){target=\_blank} function within their contracts. This function is invoked upon successful relay of the VAA **Considerations** From 6fbdc678b6820dd2c01135929b4154fecf46073a Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Thu, 1 Aug 2024 18:53:42 +0200 Subject: [PATCH 15/18] Update learn/infrastructure/relayer.md Co-authored-by: Erin Shaben --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index 9f79b21cc..e1eade88a 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -34,7 +34,7 @@ Advanced strategies can involve relayers performing untrusted off-chain computat In summary, the design of a relayer should ensure that there's a single, deterministic way to process messages in your protocol. In an optimally designed protocol, relayers should have a "correct" implementation, mirroring "crank turner" processes used elsewhere in blockchain. -## Client-Side relaying +## Client-Side Relaying Client-side relaying relies on user-facing front ends, such as a webpage or a wallet, to complete the cross-chain process. From 0519b45a88859953ff95763c6299b752e6013bed Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Thu, 1 Aug 2024 18:53:47 +0200 Subject: [PATCH 16/18] Update learn/infrastructure/.pages Co-authored-by: Erin Shaben --- learn/infrastructure/.pages | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/.pages b/learn/infrastructure/.pages index 9f6676578..048f97a9e 100644 --- a/learn/infrastructure/.pages +++ b/learn/infrastructure/.pages @@ -3,5 +3,5 @@ nav: - index.md - 'VAAs': 'vaas.md' - 'Guardians': 'guardians.md' - - 'SPY': 'spy.md' + - 'Spy': 'spy.md' - 'Relayers': 'relayer.md' From 24f255c57ef1e200359ae29ddd7563b9ddb7ce14 Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Fri, 2 Aug 2024 09:43:19 +0200 Subject: [PATCH 17/18] Update learn/infrastructure/relayer.md Co-authored-by: Dawn Kelly <83190195+dawnkelly09@users.noreply.github.com> --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index e1eade88a..db6e99034 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -41,7 +41,7 @@ Client-side relaying relies on user-facing front ends, such as a webpage or a wa **Key Features** - **Cost-Efficiency** - users only pay the transaction fee for the second transaction, eliminating any additional costs -- **No Backend Infrastructure** - the process is completely client-based, eliminating the need for a backend relaying infrastructure +- **No backend infrastructure** - the process is completely client-based, eliminating the need for a backend relaying infrastructure **Implementation** From 01db0febeb68b91334d25d8f107c561d2a78b5c3 Mon Sep 17 00:00:00 2001 From: Ilaria <43253244+ilariae@users.noreply.github.com> Date: Fri, 2 Aug 2024 09:43:26 +0200 Subject: [PATCH 18/18] Update learn/infrastructure/relayer.md Co-authored-by: Dawn Kelly <83190195+dawnkelly09@users.noreply.github.com> --- learn/infrastructure/relayer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/infrastructure/relayer.md b/learn/infrastructure/relayer.md index db6e99034..9c608f95d 100644 --- a/learn/infrastructure/relayer.md +++ b/learn/infrastructure/relayer.md @@ -40,7 +40,7 @@ Client-side relaying relies on user-facing front ends, such as a webpage or a wa **Key Features** -- **Cost-Efficiency** - users only pay the transaction fee for the second transaction, eliminating any additional costs +- **Cost-efficiency** - users only pay the transaction fee for the second transaction, eliminating any additional costs - **No backend infrastructure** - the process is completely client-based, eliminating the need for a backend relaying infrastructure **Implementation**