-
Notifications
You must be signed in to change notification settings - Fork 9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Specialized Relayer Doc Enhancement #49
base: main
Are you sure you want to change the base?
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -9,10 +9,35 @@ description: Learn about specialized relayers, which are purpose-built component | |
|
||
Wormhole is compatible with many [ecosystems](/build/start-building/supported-networks) and integration is straightforward. | ||
|
||
Specialized Relayers are custom-built components designed for specific cross-chain applications within the Wormhole protocol. Unlike standard relayers, they can perform off-chain computations and be tailored to optimize gas fees and enhance user experiences. | ||
|
||
### Key Concepts | ||
|
||
Before diving into implementation, it's crucial to understand the core components of Wormhole and how messages are sent and received across chains. This includes understanding VAAs (Verifiable Action Approvals), which are central to the security and functionality of relayers. | ||
|
||
## On-Chain Components | ||
|
||
It's important to understand some [on-chain components](#) before sending and receiving messages between chains. | ||
|
||
#### Example Real-World Example: Cross-Chain Asset Transfers | ||
|
||
Let's consider a real-world scenario where you set up a specialized relayer for asset transfers between Ethereum and Solana. | ||
|
||
1. **Setting Up the Emitter**: | ||
- Define the emitter address, which is the contract on the source chain (Ethereum) responsible for emitting the message. | ||
|
||
2. **Listening for VAAs**: | ||
- Implement a Spy process that listens for VAAs from the Guardian Network. The Spy will monitor for specific `chainID` and `emitter` values. | ||
|
||
3. **Fetching and Relaying the VAA**: | ||
- Once the VAA is detected, use the `getSignedVAAWithRetry` function to fetch it. This VAA is then relayed to the target chain (Solana) where it is processed. | ||
|
||
4. **Performing Off-Chain Computation**: | ||
- If necessary, perform any off-chain computation required before the message is relayed to the target contract. This might include gas optimization calculations or conditional logic for message delivery. | ||
|
||
5. **Deploy and Test**: | ||
- Deploy your specialized relayer and test it with a mock transaction to ensure it functions as expected. | ||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There is a page in the Infrastructure section about running a custom relaying service that covers this content. So, can you please remove this content from here and refer to that page and fill in any gaps there as needed? |
||
### Sending a Message | ||
|
||
To send a message, regardless of the environment or chain, the Core Contract is invoked with a message argument from an [emitter](/learn/glossary/#emitter). This emitter may be your contract or an existing application such as the [Token Bridge](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0003\_token\_bridge.md){target=\_blank}, or [NFT Bridge](https://github.com/wormhole-foundation/wormhole/blob/main/whitepapers/0006\_nft\_bridge.md){target=\_blank}. | ||
|
@@ -126,4 +151,4 @@ Once you have the VAA, the delivery method is chain-dependent. | |
|
||
## Reference | ||
|
||
You can read more about the architecture and core components in the [Learn section](/learn/architecture/). | ||
You can read more about the architecture and core components in the [Learn section](/learn/architecture/). |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -9,11 +9,17 @@ This documentation provides a comprehensive guide to relayers within the Wormhol | |
|
||
Relayers in the Wormhole context are processes that deliver [Verified Action Approvals (VAAs)](/learn/infrastructure/vaas/){target=\_blank} to their destination, playing a crucial role in Wormhole's security model. They can't compromise security, only availability, and act as delivery mechanisms for VAAs without the capacity to tamper with the outcome. | ||
|
||
### Types of Relayers | ||
|
||
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 | ||
- **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. | ||
|
||
### Key Differences Between Specialized and Standard Relayers | ||
|
||
Specialized Relayers are designed for specific use cases, allowing off-chain computations and custom optimizations, such as batching and conditional delivery. They provide flexibility and potential cost savings in gas fees but require additional setup and maintenance. Standard Relayers, on the other hand, offer simplicity and ease of integration but are less customizable and potentially less efficient in gas usage. | ||
|
||
## Fundamentals | ||
|
||
|
@@ -81,13 +87,38 @@ 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 | ||
|
||
**Detailed Setup Process** | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There is a page in the Infrastructure section about running a custom relaying service that covers this content. So, can you please remove this content from here and refer to that page and fill in any gaps there as needed? |
||
|
||
To assist developers in setting up specialized relayers, a more detailed walkthrough is provided: | ||
|
||
1. **Install Dependencies**: | ||
Use `npm i` to install necessary dependencies. | ||
|
||
**Troubleshooting Tip**: If you encounter an error like `npm error code 127`, ensure your Node.js and npm versions are up to date and try running the command with administrative privileges. | ||
|
||
2. **Setup the Basic Infrastructure**: | ||
You can start with the plugin relayer available in the [main Wormhole repository](https://github.com/wormhole-foundation/wormhole/tree/main/relayer){target=\_blank}. | ||
|
||
3. **Choose a Relaying Method**: | ||
- **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. | ||
|
||
4. **Real-World Example**: | ||
Let's walk through setting up a Specialized Relayer for a cross-chain asset transfer between Ethereum and Solana: | ||
|
||
- **Step 1**: Define the parameters of your relayer, such as the emitter address, sequence ID, and chain ID. | ||
- **Step 2**: Implement off-chain computation logic, if necessary, to optimize gas fees. | ||
- **Step 3**: Deploy your relayer and test it with a sample transaction. | ||
|
||
This setup ensures that your relayer is both functional and optimized for your specific use case. | ||
|
||
**Considerations** | ||
|
||
Remember, despite their name, specialized relayers still need to be considered trustless. VAAs are public and can be submitted by anyone, so developers shouldn't rely on off-chain relayers to perform any computation considered "trusted." | ||
Despite their name, specialized relayers still need to be considered trustless. VAAs are public and can be submitted by anyone, so developers shouldn't 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 availability, adding dependency for the cross-chain application | ||
- 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 availability, adding dependency for the cross-chain application. | ||
|
||
## Standard Relayers | ||
|
||
|
@@ -113,4 +144,4 @@ The standard relayer integration involves two key steps: | |
- 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 | ||
- Support may not be available for all chains |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This section doesn't actually cover any key concepts; it just mentions the importance of understanding them, so I'd like to see some links to other pages in the docs here where users can find out more information about these key concepts or for you to add content here if there is anything missing from other parts of the docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok. Will look to add links to other pages in docs here! 👍