summary fix
This commit is contained in:
Dev Bharel
commit
be195496d1
|
|
@ -15,6 +15,7 @@
|
|||
- [Advantages of xDapps](./dapps/5_advantages.md)
|
||||
|
||||
- [Wormhole](./wormhole/0_wormholeOverview.md)
|
||||
|
||||
- [What is Wormhole?](./wormhole/1_whatIsWormhole.md)
|
||||
- [Architecture Overview](./wormhole/2_architectureOverview.md)
|
||||
- [Core Layer Contracts](./wormhole/3_coreLayerContracts.md)
|
||||
|
|
@ -77,6 +78,10 @@
|
|||
- [EVM Messenger](./projects/evm-messenger/overview.md)
|
||||
- [Solidity](./projects/evm-messenger/messenger.md)
|
||||
- [JS Client](./projects/evm-messenger/client.md)
|
||||
- [Messenger](./projects/messenger/introduction.md)
|
||||
- [Prerequistes]()
|
||||
- [EVM]()
|
||||
|
||||
---
|
||||
|
||||
# Portal Token Bridge
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
# xData and xAssets
|
||||
|
||||
One of the biggest items on the wishlist of features for blockchains is the ability to detach tokens from their native chains. It is a tremendous limitation that ETH only exists on Ethereum, MATIC only exists on Polygon, and SOL only exists on Solana. It would be far more convenient if those assets existed independently of their blockchains, and were able to move freely.
|
||||
High on the wishlist of blockchain features is the ability to detach tokens from their native chains. It is a tremendous limitation that ETH only exists on Ethereum, MATIC only exists on Polygon and SOL only exists on Solana. It would be far more useful if those assets were able to move freely, independent of their native blockchains.
|
||||
|
||||
This is the concept of an **xAsset**, and it should be thought of as the next-generation _wrapped token_. The key feature of an xAsset is that it is chain and path agnostic, and thus retains fungibility regardless of where it travels. xAssets can move fluidly around the blockchain ecosystem without ever becoming double-wrapped. In a sense, xAssets are abstracted to a layer _outside_ of the blockchain ecosystem, and are then able to transact on whatever blockchain is most sensible.
|
||||
That thought underpins the idea of an **xAsset**, which could be considered a next-generation _wrapped token_. In a sense, xAssets exist on a layer _outside_ of the blockchain ecosystem, and so are able to transact on a variety of blockchains. An xAsset is chain- and path-agnostic, so it retains fungibility regardless of where it travels. xAssets can also move fluidly around the blockchain ecosystem without ever becoming double-wrapped.
|
||||
|
||||
Once you've envisioned this next-generation asset, you might think it's an excellent atomic unit for solving interoperability. However, this idea is just one step short of the real solution. Blockchains process arbitrary data nowadays, and some of that data just happens to represent assets. The full solution then - is to invent **xData**.
|
||||
Now that we've established the idea of an xAsset, you might think they're an excellent atomic unit for solving interoperability challenges. However, xAssets are just one step short of the real solution. Let's take a step back: blockchains now process arbitrary data, and some of that data just happens to represent assets. The full solution then, is to create **xData**.
|
||||
|
||||
**xData** is akin to an xAsset, in that it exists in its own layer independent of any blockchain, which is then accessible by _all_ blockchains. The only difference is that it represents arbitrary data, rather than token information.
|
||||
xData is akin to an xAsset in that it exists in its own layer independent of any blockchain, which makes xData accessible by _all_ blockchains. The difference is that xData represents arbitrary data rather the token information represented by an xAsset.
|
||||
|
||||
Cross-chain interoperability then reduces to the problem of creating and consuming xData. Once blockchains are able to read and write into this xData layer, xAssets are simply a use-case, and come as almost a natural consequence. If you have the ability to read and write data into a shared, global reservior, you can design any application you can imagine.
|
||||
Cross-chain interoperability then becomes a matter of creating, consuming and managing xData. Once blockchains have the ability to read and write data into a shared, global reservior, application design can take on innovative new dimensions.
|
||||
|
||||
In chapter 2 we'll delve deeper into how Wormhole implements this xData layer (also referred to as the 'Core' layer of Wormhole), but for now let's move on to how xDapps can be created on top of it.
|
||||
Later in this document, we'll delve deeper into how Wormhole implements this xData layer (also referred to as the 'Core' layer of Wormhole), but for now let's talk about how xData can be used to create xDapps.
|
||||
|
|
|
|||
|
|
@ -1,15 +1,13 @@
|
|||
# What is an xDapp
|
||||
# What is an xDapp?
|
||||
|
||||
The term **xDapp** is short for "Cross-Chain Decentralized Application". At first glance, this might give the impression that xDapps are simply Dapps which meddle a bit in doing cross-chain things. However, once you get into the business of building decentralized products which are designed to operate across a variety of blockchains and runtimes, you begin to see that these applications are architected in a fundamentally different fashion than traditional Dapps.
|
||||
The term **xDapp** is short for "Cross-Chain Decentralized Application". At first glance, this might give the impression that xDapps are simply Dapps that do cross-chain things. However, once you start building decentralized products designed to operate across a variety of blockchains and runtimes, it becomes clear that these applications are architected in a fundamentally different way than traditional Dapps.
|
||||
|
||||
The Wormhole Core Layer implements xData, which acts as a shared repository of data across the entire Wormhole Ecosystem. xDapps have the capacity to perform all the operations of traditional Dapps, but they also utilize this xData. This xData allows xDapp developers to build from a top-down, message-passing approach, rather than the bottom-up world of Dapp developers.
|
||||
xDapps have the capacity to perform all the operations of traditional Dapps, but they are also able to utilize xData. xData allows xDapp developers to build from a top-down, message-passing approach, rather than the bottom-up world of Dapp development. The Wormhole Core Layer implements xData, which acts as a shared repository of data across the entire Wormhole ecosystem.
|
||||
|
||||
Something we'll dive deeper into during the xDapp Architecture chapter is the philosophy of **Protocol-First Design**. Protocol First Design is an approach to building decentralized applications whereby the first order of business is to lay out your application into a series of data structures, APIs, and message payloads. Once you've laid out your application into a high-level protocol, the protocol acts as an agreement to which all of your components must adhere. From there, the smart contracts underlying this protocol can be considered an implementation detail.
|
||||
Something we'll explore further in the upcoming xDapp Architecture chapter is the philosophy of **Protocol-First Design**. Protocol First Design is an approach to building decentralized applications where the first order of business is to lay out your application into a series of data structures, APIs and message payloads. Once you've laid out your application into a high-level protocol, the protocol acts as an agreement to which all components must adhere. From there, the smart contracts underlying the protocol can be considered an implementation detail.
|
||||
|
||||
If you're familiar at all with web2 development, you'll immediately notice that this philosophy is quite analogous to microservice architecture. This is no coincidence, as similar problems should expect to be solved by similar solutions, and the Wormhole Core Layer is quite analogous to the OSI Network Model in many ways.
|
||||
If you're familiar with web2 development, you might notice that this philosophy is analogous to microservice architecture. This is no coincidence, as similar problems should expect to be solved by similar solutions, and the Wormhole Core Layer has a number of parallels to the OSI Network Model.
|
||||
|
||||
Thus, a more fitting depiction of xDapps might be to see them as **Distributed Decentralized Applications**, which have multiple, specialized components working in unison to implement a protocol which delivers a smooth, unified user experience across a variety of layer 1 ecosystems.
|
||||
Thus, a more fitting depiction of xDapps might be to see them as **Distributed Decentralized Applications** with multiple, specialized components working in unison to deliver a smooth, unified user experience across a variety of layer 1 ecosystems.
|
||||
|
||||
---
|
||||
|
||||
So far we've taken a really high-level and abstract approach to explaining what xDapps are. In the next section we'll get back to real world, and summarize the concrete advantages which xDapps built on Wormhole have over traditional apps today.
|
||||
In the next section, we'll summarize the concrete advantages which xDapps built on Wormhole have over traditional Dapps today.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,19 @@
|
|||
Let's wrap up our discussion of xDapps by highlighting the features they enable, and how they move the ball forward in blockchain technologies.
|
||||
# Advantages of xDapps
|
||||
|
||||
- **Expanded User Base** - rather than being limited to the users of one blockchain, any user on any blockchain in the supported ecosystem can interact with an xDapp.
|
||||
Here are a few xDapp features that are making an impact across blockchain technologies:
|
||||
|
||||
- **Unified Liquidity** - Liquidity fragmentation is a major problem in the current ecosystem. xAssets, unlike traditional tokens, can be pooled and moved anywhere necessary.
|
||||
- **Expanded User Base** - Rather than being limited to the users of one blockchain, any user on any blockchain in the ecosystem can interact with an xDapp.
|
||||
|
||||
- **Decentralization** - Cross-chain solutions today usually involve highly centralized exchanges or bridges. Wormhole has been designed to be decentralized from day one, and eventually totally trustless.
|
||||
- **Unified Liquidity** - Liquidity fragmentation is a major problem in the current ecosystem. Unlike traditional tokens, xAssets can be pooled and moved anywhere.
|
||||
|
||||
- **Increased Performance** - xDapps are able to utilize the strengths of each blockchain. Expensive computations can be offloaded onto high-performance platforms. Final settlement can be on the preferred chain of the user. Data can be stored wherever is cheapest.
|
||||
- **Decentralization** - Cross-chain solutions today usually involve centralized exchanges or bridges. However, Wormhole has been designed to be decentralized from day one, and eventually totally trustless.
|
||||
|
||||
- **Broader Market Reach** - Because xAssets move freely through the ecosystem, they can be listed on a variety of exchanges, and custodied on any blockchain.
|
||||
- **Increased Performance** - xDapps are able to utilize the strengths of each blockchain. With xDapps, expensive computations can be offloaded onto high-performance platforms, final settlement can take place on a preferred chain and data can be stored wherever is cheapest.
|
||||
|
||||
- **Increased Extensibility and Composeability** - xDapps expand upon the composeability and openness of smart contracts. xDapps can utilize anything across the ecosystem, including other xDapps.
|
||||
- **Broader Market Reach** - Because xAssets move freely through the ecosystem, they can be listed on a variety of exchanges and custodied on any blockchain.
|
||||
|
||||
- **Future Proofing** - As new environments and protocols join the decentralized ecosystem, the connected nature of the Wormhole ecosystem allows existing protocols to expand and support them.
|
||||
- **Increased Extensibility and Composeability** - xDapps can utilize anything across the ecosystem, including other xDapps, expanding upon the composability and openness of smart contracts.
|
||||
|
||||
Now that you have an understanding of what xDapps are and the advantages they offer, let's move on to the next chapter, where we will delve into the nitty gritty of how Wormhole works, and how it enables the creation of these next-generation protocols.
|
||||
- **Futureproofing** - As new environments and protocols join the decentralized ecosystem, the connected nature of the Wormhole ecosystem allows existing protocols to expand and support them.
|
||||
|
||||
Now that you have an understanding of what xDapps are and the advantages they offer, let's move on to the next chapter where we will delve into how Wormhole works and how it enables the creation of these next-generation protocols.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,21 @@
|
|||
# Orchestrator.js
|
||||
# EVM Messenger Client
|
||||
|
||||
Let's walk through a few of the elements of the EVM Messenger client you'll see in the project folders:
|
||||
|
||||
## Orchestrator.js
|
||||
A JS client that deploys and calls the functions of the two Messenger contracts on two chains.
|
||||
|
||||
## Deploy
|
||||
Uses [forge](https://getfoundry.sh) to compile and deploy the code. Stores the deployed address to be used later.
|
||||
|
||||
## Register Chain
|
||||
Takes the deployed address from the target chain and registers it on the source chain. No wormhole interaction is necessary for this step.
|
||||
Takes the deployed address from the target chain and registers it on the source chain. No Wormhole interaction is necessary for this step.
|
||||
|
||||
## Send Msg
|
||||
Calls the `sendMsg()` function on the source chain, which emits a VAA. Fetches the VAA from the Wormhole guardian after it's ready, then stores it.
|
||||
Calls the `sendMsg()` function on the source chain, which emits a VAA. Fetches the VAA from the Wormhole Guardian and stores it.
|
||||
|
||||
## Submit VAA
|
||||
Manually relays the VAA to the target chain.
|
||||
|
||||
## Get Current Msg
|
||||
Returns the chain's current message.
|
||||
Returns the chain's current message.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Messenger.sol
|
||||
Messenger.sol an application contract on EVM that is capable of communicating with the Wormhole core bridge.
|
||||
Messenger.sol is an application contract on EVM capable of communicating with the Wormhole core bridge.
|
||||
|
||||
We start with hard coding the Wormhole core bridge address, and creating a interfaced link to it.
|
||||
Start by hard coding the Wormhole core bridge address, and creating a interfaced link to it.
|
||||
|
||||
```solidity
|
||||
//SPDX-License-Identifier: Unlicense
|
||||
|
|
@ -26,7 +26,7 @@ contract Messenger {
|
|||
```
|
||||
|
||||
## Constructor
|
||||
Nothing fancy, just setting the owner of the contract to the deployer. The owner is used later to register sibling contracts on foreign chains.
|
||||
This sets the owner of the contract to the deployer. The owner is used later to register sibling contracts on foreign chains.
|
||||
|
||||
```solidity
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ constructor(){
|
|||
```
|
||||
|
||||
## SendMsg
|
||||
Takes in a bytes payload and calls the Wormhole Core Bridge to publish the bytes as a message.
|
||||
This takes in a bytes payload and calls the Wormhole Core Bridge to publish the bytes as a message.
|
||||
|
||||
The `publishMessage()` function of the core_bridge take three arguements:
|
||||
- Nonce: a number to uniquely identify this message, used to make sure that the target chain doesn't double process the same message
|
||||
|
|
@ -52,7 +52,7 @@ function sendMsg(bytes memory str) public returns (uint64 sequence) {
|
|||
```
|
||||
|
||||
## ReceiveEncodedMsg
|
||||
The receive encoded message takes in a VAA as bytes. Then it calls the Core Bridge to verify the signatures match those of the gaurdians, check that it's from a contract on a foreign chain that we actually want to listen to, and that the message hasn't been processed already. If all those checks pass, we can decode the payload (in this case we know it's a string) and set the current_msg for the contract to that payload.
|
||||
The receive encoded message takes in a VAA as bytes. Then it calls the Core Bridge to verify the signatures match those of the gaurdians, check that it's from a contract on a foreign chain that we actually want to listen to and that the message hasn't been processed already. If all those checks pass, we can decode the payload (in this case we know it's a string) and set the current_msg for the contract to that payload.
|
||||
|
||||
```solidity
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ function receiveEncodedMsg(bytes memory encodedMsg) public {
|
|||
```
|
||||
|
||||
## GetCurrentMsg
|
||||
Simple method that just returns what the current stored message is.
|
||||
A simple method that returns the current stored message.
|
||||
|
||||
```solidity
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ function getCurrentMsg() public view returns (string memory){
|
|||
```
|
||||
|
||||
## RegisterApplicationContracts
|
||||
Generally, you want to register and track what contracts from foreign chains you're accepting VAAs from because anyone could deploy a contract and generate a fake VAA that looks like a real VAA you want to accept.
|
||||
It's typically a good idea to register and track the contracts from foreign chains that you're accepting VAAs from, as anyone could deploy a contract and generate a fake VAA that looks like a real VAA you'd want to accept.
|
||||
|
||||
```solidity
|
||||
|
||||
|
|
@ -102,4 +102,4 @@ function registerApplicationContracts(uint16 chainId, bytes32 applicationAddr) p
|
|||
_applicationContracts[chainId] = applicationAddr;
|
||||
}
|
||||
|
||||
```
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,23 +1,25 @@
|
|||
# EVM Messenger
|
||||
|
||||
The EVM messenger project is a very simple contract that sends messages from one contract on an EVM chain to it's sibling contract on Chain B. Before you get started with this project, make sure you have a local Wormhole Guardian Network running (either [WLV](../../development/wormhole-local-validator.md) or [Tilt](../../development/tilt/overview.md)). If you're running WLV, you'll also need to spin up EVM0 and EVM1 so we have two EVM chains to send messages back and forth.
|
||||
The EVM messenger project is a simple contract that sends messages from one contract on an EVM chain to its sibling contract on another chain.
|
||||
|
||||
Let's break down the files you're going to find in [evm-messenger](https://github.com/certusone/xdapp-book/tree/main/projects/evm-messenger) folder.
|
||||
Before you get started with this project, make sure you have a local Wormhole Guardian Network running (either [WLV](../../development/wormhole-local-validator.md) or [Tilt](../../development/tilt/overview.md)). If you're running WLV, you'll also need to spin up EVM0 and EVM1 so there are two EVM chains to send messages back and forth.
|
||||
|
||||
Let's break down the files you're going to find in the [evm-messenger](https://github.com/certusone/xdapp-book/tree/main/projects/evm-messenger) folder.
|
||||
|
||||
### Chains
|
||||
Firstly, the `chains/` folder contains the source code that's actually being deployed to the EVM chain. The `evm/` folder found inside was generated using [`forge init`](https://getfoundry.sh). There's two files to of note in this folder, `src/Wormhole/IWormhole.sol` and `src/Messenger.sol`.
|
||||
The `chains/` folder contains the source code that's actually being deployed to the EVM chain. The `evm/` folder found inside was generated using [`forge init`](https://getfoundry.sh). There are two files of note in this folder, `src/Wormhole/IWormhole.sol` and `src/Messenger.sol`.
|
||||
|
||||
The IWormhole file is the Wormhole Core Bridge interface and required if your app wants to be able to talk to the Wormhole Core Bridge. It outlines the functions and return values you can expect from the Wormhole contract.
|
||||
The IWormhole file is the Wormhole Core Bridge interface, and is required if your app wants to talk to the Wormhole Core Bridge. It outlines the functions and return values you can expect from the Wormhole contract.
|
||||
|
||||
The second file, Messenger, we will cover in our breakdown of the EVM code [here](./messenger.md).
|
||||
The second file, Messenger, is covered in our breakdown of the EVM code [here](./messenger.md).
|
||||
|
||||
### Tests
|
||||
We have a very very simple test script written in bash. It's less of a test script and more of a happy path walkthrough. It makes uses of Orchestrator.js (see below) to call the functions on our EVM contract in order.
|
||||
We have a very simple test script written in bash, but it's less of a test script and more of a happy path walkthrough. It makes uses of Orchestrator.js (see below) to call the functions on our EVM contract in order.
|
||||
|
||||
We first deploy the code, register the applications on each chain, and then send a message.
|
||||
To start, deploy the code, register the applications on each chain and then send a message.
|
||||
|
||||
### Orchestrator
|
||||
Orchestrator is a very simple js client that takes arguements from the command line to call the various functions on our contract. We'll break down everything orchestator does [here](./client.md).
|
||||
Orchestrator is a js client that takes arguments from the command line to call various functions on our contract. We'll break down everything orchestator does [here](./client.md).
|
||||
|
||||
### xdapp.config.json
|
||||
This maintains some constants about the chains RPC endpoints, private keys used to deploy code, etc. Also includes the Wormhole RPC endpoint.
|
||||
This maintains some constants about the chains RPC endpoints, private keys used to deploy code, etc. It also includes the Wormhole RPC endpoint.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Repository
|
||||
Wormhole core repository is [here](https://github.com/certusone/wormhole).
|
||||
The Wormhole core repository can be found [here](https://github.com/certusone/wormhole).
|
||||
|
||||
|
||||
|
||||
# Design Documents
|
||||
|
||||
Wormhole's components are designed via specifications that can be found [here](https://github.com/certusone/wormhole/tree/dev.v2/whitepapers). These outline the reasoning behind design decisions and details specifics in more technical depth.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,17 @@
|
|||
# Tools
|
||||
There's various tools in the Wormhole ecosystem that can help you in developing xDapps.
|
||||
There are various tools in the Wormhole ecosystem that can help you in developing xDapps. Here are a few of the most notable:
|
||||
|
||||
# Testnet
|
||||
Wormhole has deployed Core Bridge, Token Bridge, and NFT Bridge contracts on the various testnets of the chains that Wormhole connects to. 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 will 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). 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 Explorer
|
||||
Wormhole Explorer is a tool that will help you parse VAAs after they've been picked up the Guardian network. It's available [here](https://wormholenetwork.com/en/explorer).
|
||||
|
||||
# Testnet Bridge UI
|
||||
If you'd like to try out Portal Bridge on Testnet, there's a UI you can use to attest and transfer tokens for testnet. It's hosted [here](https://certusone.github.io/wormhole).
|
||||
If you'd like to try out Portal Bridge on Testnet, there's a UI you can use to attest and transfer tokens for testnet, hosted [here](https://certusone.github.io/wormhole).
|
||||
|
||||
# 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 get it setup and test against it, check it out [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. To set it up and test against it, start [here](../development/tilt/overview.md).
|
||||
|
||||
# Wormhole SDK
|
||||
The SDK is a set of Javascript tools to help you do Token Bridge transfers, fetch and submit VAAs from one chain to another. You can install it via NPM [here](https://www.npmjs.com/package/@certusone/wormhole-sdk).
|
||||
The SDK is a set of Javascript tools to help you do Token Bridge transfers, plus fetch and submit VAAs from one chain to another. You can install it via NPM [here](https://www.npmjs.com/package/@certusone/wormhole-sdk).
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
# Wormhole
|
||||
|
||||
In the previous chapter, we established concepts like xDapps, xData, and xAssets. In this chapter, we'll dive into the inner workings of the Wormhole ecosystem, and how they give rise to these ideas.
|
||||
In the previous chapter, we established concepts like xDapps, xData and xAssets. In this chapter, we'll focus on the inner workings of the Wormhole ecosystem and how they power these ideas.
|
||||
|
||||
By the end of this chapter, you should have a clear understanding of what Wormhole is, what its key components are, and how each of those components comes together to create a powerful, new cross-chain ecosystem.
|
||||
By the end of this chapter, you'll have a clear understanding of what Wormhole is, what its key components are and how each component comes together to create a powerful, new cross-chain ecosystem.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
# What is Wormhole?
|
||||
|
||||
Wormhole was first conceived in 2020 by Certus One, and was initially scoped as a traditional token bridge between Ethereum and Solana. The Wormhole v1 Token Bridge was the first bridge on Solana, and was responsible for bootstrapping a large amount of the liquidity in the early Solana and Serum ecosystems.
|
||||
Wormhole was introduced in 2020 by Certus One, and was initially conceived as a traditional token bridge between Ethereum and Solana. The Wormhole v1 Token Bridge was the first bridge on Solana and was responsible for bootstrapping a large amount of the liquidity in the early Solana and Serum ecosystems.
|
||||
|
||||
Despite its beginnings as a token bridge, Wormhole quickly grew beyond Solana, and beyond the domain of token transfers.
|
||||
However, despite its beginnings as a token bridge, Wormhole quickly grew beyond Solana and token transfers.
|
||||
|
||||
Wormhole v2 launched in August 2021 as a decentralized generic interoperability protocol for multiple blockchain ecosystems, with initial support for Solana, Terra, Ethereum, and Binance Smart Chain.
|
||||
Wormhole v2 launched in August 2021 as a decentralized generic interoperability protocol for multiple blockchain ecosystems with initial support for Solana, Terra, Ethereum and Binance Smart Chain.
|
||||
|
||||
Over the past year, Wormhole has grown to support an ever-growing list of blockchains, across an unrivaled number of smart contract runtimes.
|
||||
Over the past year, Wormhole has evolved to support an ever-growing list of blockchains across an unrivaled number of smart contract runtimes.
|
||||
|
||||
While Wormhole is a generic interoperability protocol, it is also an ecosystem and platform for developers to grow the decentralized computing space. Wormhole consists of multiple modular swap-in components which can be leveraged independently, and supports a growing number of composible applications built by numerous teams.
|
||||
While Wormhole is a generic interoperability protocol, it is also an ecosystem and platform for developers to grow the decentralized computing space. Wormhole consists of multiple modular swap-in components that can be leveraged independently and supports a increasing number of composible applications built by numerous teams.
|
||||
|
||||
In the next section, we'll go over the major components of the Wormhole ecosystem, and how they fit together to enable the high-level cross chain functionality required to develop xDapps.
|
||||
In the next section, we'll go over the major components of the Wormhole ecosystem and how they fit together to enable the cross-chain functionality required to develop xDapps.
|
||||
|
|
|
|||
|
|
@ -1,33 +1,37 @@
|
|||
# Architecture Overview
|
||||
|
||||
Wormhole is a fairly complex ecosystem, with several noteworthy components. Before we go in depth into each component, let's take a moment to lay out the names of the major pieces, and how they fit together.
|
||||
Wormhole is a complex ecosystem with several noteworthy components. Before we go into each component in depth, let's talk about the names of the major pieces and how they fit together.
|
||||
|
||||
|
||||
|
||||
### On-Chain Components
|
||||
|
||||
- **xDapp Contracts** - these are contracts developed by xDapp developers. They receive transactions from the end user, and then interact with other xDapp contracts and Wormhole Ecosystem Contracts in order to provide their service.
|
||||
- **Ecosystem Contracts** - these are contracts inside the Wormhole Ecosystem, subject to Wormhole governance. Their job is to provide the feature suite of Wormhole to xDapp developers.
|
||||
- **xDapp Contracts** - Contracts developed by xDapp developers. They receive transactions from the end user and then interact with other xDapp contracts and Wormhole Ecosystem Contracts in order to provide their service.
|
||||
|
||||
- **Core Contracts** - these are the primary ecosystem contracts. These are the contracts which the Guardians observe, and which fundamentally allow for cross-chain communication.
|
||||
- **Portal xAsset Contracts** - these contracts allow normal tokens to be converted to xAssets, and enable these xAssets to be bridged around the ecosystem.
|
||||
- **Relay Contracts** - _in development\*_ - allow xDapps to send messages to a specific blockchain, via the use of the decentralized Generic Relayer network.
|
||||
- **Gas Oracle** - _in development\*_ - oracle for recommended fair gas prices across the ecosystem.
|
||||
- **Ecosystem Contracts** - Contracts subject to Wormhole governance which live inside the Wormhole Ecosystem. Their job is to provide the feature suite of Wormhole to xDapp developers.
|
||||
|
||||
- **Core Contracts** - Primary ecosystem contracts. These are the contracts which the Guardians observe and which fundamentally allow for cross-chain communication.
|
||||
|
||||
- **Portal xAsset Contracts** - Contracts that allow normal tokens to be converted to xAssets and enable these xAssets to be bridged.
|
||||
|
||||
- **Relay Contracts** - _in development\*_ - Contracts that allow xDapps to send messages to a specific blockchain via the decentralized Generic Relayer network.
|
||||
|
||||
- **Gas Oracle** - _in development\*_ - Oracle for recommended fair gas prices across the ecosystem.
|
||||
|
||||
### Off-Chain Components
|
||||
|
||||
- **Guardian Network** - Guardians exist in their own p2p network. They observe the Core Contract on each supported chain, and produce VAAs (signed messages) when those contracts receive an interaction.
|
||||
- **Guardian Network** - Validators that exist in their own p2p network. Guardians observe the Core Contract on each supported chain and produce VAAs (signed messages) when those contracts receive an interaction.
|
||||
|
||||
- **Guardian** - One of the validators in the Guardian Network which contributes to the VAA multisig. There are currently exactly 19 Guardians.
|
||||
- **Guardian** - One of 19 validators in the Guardian Network that contributes to the VAA multisig.
|
||||
|
||||
- **Spy** - Validators on the Guardian Network which are not part of the Guardian set. These spies can observe and forward network traffic, which helps scale up VAA distribution.
|
||||
- **Spy** - Validators on the Guardian Network which are not part of the Guardian set. A spy can observe and forward network traffic, which helps scale up VAA distribution.
|
||||
|
||||
- **Wormchain** - _in development\*_ - a purpose built cosmos blockchain which aids the Guardian Network, and allows for formal interaction with the Guardians.
|
||||
- **Wormchain** - _in development\*_ - A purpose-built cosmos blockchain which aids the Guardian Network and allows for formal interaction with the Guardians.
|
||||
|
||||
- **Specialized Relayers** - relayers which only handle VAAs for a specific protocol or xDapp. This allows them to execute custom logic off-chain, which can reduce gas costs and increase cross-chain compatibility. Currently, xDapp developers are responsible for developing and hosting this component.
|
||||
- **Specialized Relayers** - Relayers that only handle VAAs for a specific protocol or xDapp. This allows them to execute custom logic off-chain, which can reduce gas costs and increase cross-chain compatibility. Currently, xDapp developers are responsible for developing and hosting specialized relayers.
|
||||
|
||||
- **Generic Relayers** - _in development\*_ - a decentralized relayer network which delivers messages that are requested on-chain via the Wormhole Relay Contract.
|
||||
- **Generic Relayers** - _in development\*_ - A decentralized relayer network which delivers messages that are requested on-chain via the Wormhole Relay Contract.
|
||||
|
||||
- **VAAs** - Verifiable Action Approvals - These are the key piece of data in the Wormhole ecosystem. They contain the messages which are emitted by xDapps, along with information such as what contract emitted the message. The VAAs are signed by the Guardians, and need 13/19 signatures in order to be considered authentic.
|
||||
- **VAAs** - Verifiable Action Approvals (VAAs) are the key piece of data in the Wormhole ecosystem, containing the messages emitted by xDapps along with information such as what contract emitted the message. The VAAs are signed by the Guardians and need 13/19 signatures to be considered authentic.
|
||||
|
||||
\*\*Features listed as _in development_ are not yet available in mainnet.
|
||||
|
|
|
|||
|
|
@ -1,51 +1,55 @@
|
|||
# Core Contracts
|
||||
|
||||
The Wormhole Core Contracts are one of the most pivotal pieces of the Wormhole ecosystem, and serve as a great place to start when learning about how data flows through the ecosystem.
|
||||
The Core Contracts are the mechanism by which all Wormhole messages are emitted. All xDapps either interact directly with the Core Contract or interact with another contract that does. There is one Core Contract on each blockchain in the ecosystem, and this is the contract which the Guardians are required to observe.
|
||||
|
||||
There is one Core Contract on each blockchain in the ecosystem, and this is the contract which the Guardians are required to observe. The Core Contracts are the mechanism by which all Wormhole messages are emitted. All xDapps either interact directly with the Core Contract, or interact with some other contract which does.
|
||||
The Wormhole Core Contracts are one of the most pivotal pieces of the Wormhole ecosystem. They serve as a great place to start when learning about how data flows through the ecosystem.
|
||||
|
||||
The Core Contracts are quite simple and only have a few public-facing functions.
|
||||
In general, Core Contracts are simple with only a few public-facing functions, which we'll define next.
|
||||
|
||||
---
|
||||
|
||||
First, we have the 'sending' side of the Core Contract:
|
||||
|
||||
publishMessage(
|
||||
int nonce,
|
||||
byte[] payload,
|
||||
int consistencyLevel
|
||||
) returns int sequenceNumber
|
||||
|
||||
This is the mechanism by which Wormhole Messages are emitted.
|
||||
This is the foundational mechanism by which Wormhole Messages are emitted. Let's break it down a bit:
|
||||
|
||||
- **payload** is an arbitrary byte array, and is the content of the emitted message. It may be capped to a certain maximum length due to the constraints of individual blockchains.
|
||||
- **consistencyLevel** is the number of blocks which the guardians should wait prior to emitting a VAA for this message. This number is usually either 1, or equal to the chain's finality period. This is a defense against transactions being orphaned.
|
||||
- **nonce** - on chains where batch VAAs are supported, if multiple messages in the same transaction have the same nonce, a batch VAA will be produced alongside the individual VAAs. This feature reduces gas costs and simplifies composeability.
|
||||
- **payload** - The content of the emitted message and an arbitrary byte array. It may be capped to a certain maximum length due to the constraints of individual blockchains.
|
||||
|
||||
- **sequenceNumber** - this is a unique index number for the message. When combined with the emitter contract address and emitter chain ID, the corresponding VAA can be retrieved from a guardian network node.
|
||||
- **consistencyLevel** - The number of blocks which the Guardians should wait prior to emitting a VAA for this message. This number is usually either 1 or equal to the chain's finality period. This is a defense against transactions being orphaned.
|
||||
|
||||
The implementation strategy for publishMessage differs by chain. However, the general strategy is that the Core Contract will post the emitterAddress (the contract which called publishMessage), sequenceNumber, and consistencyLevel into the blockchain logs. Once the desired consistencyLevel has elapsed, the Guardian Network will produce the requested VAAs.
|
||||
- **nonce** - If multiple messages in the same transaction have the same nonce, a batch VAA will be produced alongside the individual VAAs on chains that allow them. This reduces gas costs and simplifies composeability.
|
||||
|
||||
Currently there are no fees to publish a message, except when publishing on Solana. This is not guaranteed to always be the case, however.
|
||||
- **sequenceNumber** - A unique index number for the message. When combined with the emitter contract address and emitter chain ID, the corresponding VAA can be retrieved from a guardian network node.
|
||||
|
||||
The implementation strategy for publishMessage differs by chain, but the general strategy consists of the Core Contract posting the emitterAddress (the contract which called publishMessage), sequenceNumber, and consistencyLevel into the blockchain logs. Once the desired consistencyLevel has elapsed, the Guardian Network will produce the requested VAAs.
|
||||
|
||||
Currently there are no fees to publish a message (with the exception of publishing on Solana) but this is not guaranteed to always be the case in the future.
|
||||
|
||||
---
|
||||
|
||||
Second, we have 'receiving' side of the Core contract.
|
||||
Next, we have the 'receiving' side of the Core Contract.
|
||||
|
||||
parseAndVerifyVAA( byte[] VAA )
|
||||
|
||||
This function, when passed a VAA, will either return the payload and associated metadata for the VAA, or throw an exception. An exception should only ever throw if the VAA fails signature verification, which would indicate that the VAA is invalid or inauthentic in some form.
|
||||
When passed a VAA, this function will either return the payload and associated metadata for the VAA or throw an exception. An exception should only ever throw if the VAA fails signature verification, indicating the VAA is invalid or inauthentic in some form.
|
||||
|
||||
---
|
||||
|
||||
## Multicasting
|
||||
|
||||
Let's take a moment to point out that there is no inclusion of any destination address or chain in these functions.
|
||||
Let's take a moment to point out that there is no destination address or chain in these functions.
|
||||
|
||||
VAAs simply attest that "This contract on this chain said this thing". Therefore, VAAs are multicast by default, and will be verified as authentic on any chain they are brought to.
|
||||
VAAs simply attest that "this contract on this chain said this thing." Therefore, VAAs are multicast by default and will be verified as authentic on any chain they are brought to.
|
||||
|
||||
This multicast-by-default model is intentional, and also integral to the design. Having this multicast capacity makes it easy to synchronize state across the entire ecosystem, because a single blockchain can make its data available to every chain in a single action with low latency. This, in turn, reduces the complexity of the n^2 problems encountered by routing data to a large number of blockchains.
|
||||
This multicast-by-default model is integral to the design. Having this multicast capacity makes it easy to synchronize state across the entire ecosystem, because a single blockchain can make its data available to every chain in a single action with low latency. This reduces the complexity of the n^2 problems encountered by routing data to a large number of blockchains.
|
||||
|
||||
Use cases where the message has an intended recipient or is only meant to be consumed once must be handled in logic outside the Core Contract. There are standard practices for accomplishing these features shown later on in the code examples, and some ecosystem contracts (namely Portal & the Relaying contract) handle this on behalf of downstream consumers.
|
||||
Use cases where the message has an intended recipient or is only meant to be consumed a single time must be handled in logic outside the Core Contract. There are standard practices for accomplishing these features later on in the code examples, and some ecosystem contracts (namely Portal & the Relaying contract) handle this on behalf of downstream consumers.
|
||||
|
||||
Lastly, because the VAA creation is a separate concern from relaying, there is _no additional cost_ to this multicast model when a single chain is being targetted. If the data isn't needed on a certain blockchain, don't relay it there, and it won't cost anything.
|
||||
Lastly, because the VAA creation is separate from relaying, there is _no additional cost_ to the multicast model when a single chain is being targetted. If the data isn't needed on a certain blockchain, don't relay it there, and it won't cost anything.
|
||||
|
||||
In the next section we'll dive into the technical specfications of the VAA.
|
||||
In our next section, we'll dive into the technical specfications of the VAA.
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# VAAs (Verified Action Approval)
|
||||
# VAAs (Verified Action Approvals)
|
||||
|
||||
VAAs are the core messaging primative in Wormhole. You can think of them as packets of xData. Any time an xDapp contract interacts with the Core Contract, a VAA is emitted.
|
||||
VAAs are the core messaging primative in Wormhole. You can think of them as packets of xData that are emitted any time an xDapp contract interacts with the Core Contract.
|
||||
|
||||
The basic VAA has two components, a Header and a Body.
|
||||
The basic VAA has two components--a Header and a Body.
|
||||
|
||||
## Header
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ The basic VAA has two components, a Header and a Body.
|
|||
u8 len_signatures (Number of signatures stored)
|
||||
[][66]byte signatures (Collection of ecdsa signatures)
|
||||
|
||||
The header is used by the Core Contract to determine the authenticity of the VAA, but can generally be ignored by other consumers.
|
||||
The Header is used by the Core Contract to determine the authenticity of the VAA, but can generally be ignored by other consumers.
|
||||
|
||||
## Body
|
||||
|
||||
|
|
@ -23,18 +23,18 @@ The header is used by the Core Contract to determine the authenticity of the VAA
|
|||
u8 consistency_level (How many blocks were waited before emitting this VAA)
|
||||
[]byte payload (VAA message content)
|
||||
|
||||
The body is the relevant information for consumers, and is handed back from parseAndVerifyVAA. Because the emitterAddress is included as part of the body, the developer is able to discern if this VAA originated from a trusted contract.
|
||||
The Body is the relevant information for consumers and is handed back from parseAndVerifyVAA. Because the emitterAddress is included as part of the Body, the developer is able to tell if this VAA originated from a trusted contract.
|
||||
|
||||
VAAs are uniquely indexed by their emitterChain, emittedAddress, and sequence. VAAs can be obtained by querying a node in the Guardian Network with this information.
|
||||
VAAs are uniquely indexed by their emitterChain, emittedAddress and sequence. They can be obtained by querying a node in the Guardian Network with this information.
|
||||
|
||||
Because baseline VAAs have no destination, they are effectively multicast. They will be verified as authentic by any Core Contract on any chain in the network, and it is entirely the responsibility of relayers to deliver VAAs to the appropriate destination.
|
||||
Because baseline VAAs have no destination, they are effectively multicast. They will be verified as authentic by any Core Contract on any chain in the network, and it is entirely the responsibility of relayers to deliver VAAs to the appropriate place.
|
||||
|
||||
## Batch VAAs
|
||||
|
||||
Certain blockchains support version 2 VAAs, also referred to as **Batch VAAs**. When multiple messages with the same nonce are emitted in the same transaction, a batch VAA will be created in addition to the individual VAAs. The Batch VAA contains the body of each individual VAA, but only has a single header. This reduces the gas cost of verifying the VAA, and also simplifies the process of relaying and consuming multiple VAAs.
|
||||
Certain blockchains support version 2 VAAs, also referred to as **Batch VAAs**. When multiple messages with the same nonce are emitted in the same transaction, a batch VAA will be created in addition to the individual VAAs. The Batch VAA contains the body of each individual VAA, but only has a single header. This reduces the gas cost of verifying the VAA, and simplifies the process of relaying and consuming multiple VAAs.
|
||||
|
||||
Batch VAAs are not currently live on mainnet, but will have initial support on all EVM chains when they launch.
|
||||
|
||||
---
|
||||
|
||||
In the next section, we will give an overview of how the Wormhole Guardian network creates these VAAs, and the key design considerations which underpin the network.
|
||||
In the next section, we'll give an overview of how the Wormhole Guardian network creates VAAs along with a look at the key design considerations that underpin the network.
|
||||
|
|
|
|||
|
|
@ -1,58 +1,58 @@
|
|||
# Guardian Network
|
||||
|
||||
The Guardian Network is the backbone and most critical component of the Wormhole ecosystem. It is designed to serve as Wormhole's oracle component, and the rest of the Wormhole ecosystem is really founded upon the technical underpinnings of this network. Therefore, this is the single most important component to learn about if you want a deep understanding of Wormhole.
|
||||
The Guardian Network is designed to serve as Wormhole's oracle component, and the entire Wormhole ecosystem is founded on its technical underpinnings. It is the most critical element of the Wormhole ecosystem, and represents the single most important component to learn about if you want a deep understanding of Wormhole.
|
||||
|
||||
To understand not just _how_ the Guardian Network works, but also _why_ it works the way it does, let's first take a step back, and go over the key considerations which went into the design. There were essentially five critical features which Wormhole needed to have in order to become the best-in-class interoperability platform.
|
||||
To understand not just _how_ the Guardian Network works, but _why_ it works the way it does, let's first take a step back and go over the key design considerations. To become the best-in-class interoperability platform, there were five critical features Wormhole needed to have:
|
||||
|
||||
1. **Decentralization** - Control of the network needs to be distributed amongst many parties.
|
||||
2. **Modularity** - Disparate parts of the ecosystem such as the oracle, relayer, applications, etc, should be kept as separate and modular as possible so they can be designed, modified, and upgraded independently.
|
||||
3. **Chain Agnosticism** - Wormhole should be able to support not only EVM, but also chains like Solana, Algorand, Cosmos, and even platforms which have not even yet been created. It also should not have any one chain as a single point of failure.
|
||||
4. **Scalablity** - Wormhole should be able to secure a large amount of value immediately, and should also be able to handle the large transaction volume which will come from high-performance blockchains like Solana.
|
||||
5. **Upgradeability** - As the decentralized computing ecosystem evolves and new tech becomes prevalent, Wormhole will need to be able to change the implementation of its existing modules without breaking integrators.
|
||||
2. **Modularity** - Disparate parts of the ecosystem such as the oracle, relayer, applications, etc, should be kept as separate and modular as possible so they can be designed, modified and upgraded independently.
|
||||
3. **Chain Agnosticism** - Wormhole should be able to support not only EVM, but also chains like Solana, Algorand, Cosmos, and even platforms that haven't been created yet. It also should not have any one chain as a single point of failure.
|
||||
4. **Scalablity** - Wormhole should be able to secure a large amount of value immediately and be able to handle the large transaction volume.
|
||||
5. **Upgradeability** - As the decentralized computing ecosystem evolves, Wormhole will need to be able to change the implementation of its existing modules without breaking integrators.
|
||||
|
||||
Next, let's go into how Wormhole achieves these one at a time.
|
||||
|
||||
## Decentralization
|
||||
|
||||
Decentralization is the biggest item. Previous interoperability solutions have largely been entirely centralized, and even newer solutions which utilize things like adversarial relayers still tend to have single points of failure or collusion thresholds as low as 1 or 2.
|
||||
Decentralization is the biggest concern. Previous interoperability solutions have largely been entirely centralized, and even newer solutions utilizing things like adversarial relayers still tend to have single points of failure or collusion thresholds as low as 1 or 2.
|
||||
|
||||
In designing a decentralized oracle network, the first option to consider is probably a Proof-of-Stake system. However, upon closer inspection, this actually turns out to be a suboptimal solution. PoS is designed for blockchain consensus in smart-contract enabled environments, and it's less suitable when the network is verifying the output of many blockchains and not supporting its own smart contracts. While it looks appealing from a decentralization perspective, the network security is somewhat unclear, and it also makes some of the other outlined goals more difficult to achieve, so let's discuss other options.
|
||||
When designing a decentralized oracle network, the first option to consider is likely a Proof-of-Stake (PoS) system--but this turns out to be a suboptimal solution. PoS is designed for blockchain consensus in smart-contract enabled environments, so it's less suitable when the network is verifying the output of many blockchains and not supporting its own smart contracts. While it looks appealing from a decentralization perspective, the network security remains unclear, and it can makes some of the other outlined goals more difficult to achieve. Let's explore other options.
|
||||
|
||||
The first option would be to rush straight for the finish line, and use zero-knowledge proofs in order to secure the network. This would be the best from a decentralization perspective, as it's literally trustless. However, zero knowledge proofs are still a nascent technology, and it's not really feasible to verify them on-chain, especially on chains with limited computational environments. Thus, some form of multisig will be needed to secure the network.
|
||||
The next option would be to rush straight for the finish line and use zero-knowledge proofs to secure the network. This would be the a good solution from a decentralization perspective, as it's literally trustless. However, zero-knowledge proofs are still a nascent technology and it's not really feasible to verify them on-chain, especially on chains with limited computational environments. That means a form of multisig will be needed to secure the network.
|
||||
|
||||
If we take a step away from game-theoretic considerations of various consensus models and look at the current De-Fi landscape, it's easy to see that most of the top blockchains are secured by the same handful of validator companies. The reality is that at this point in time there are only a limited number of companies in the world with the skills and capital to run top-notch validator companies.
|
||||
If we step back and look at the current De-Fi landscape, most of the top blockchains are secured by the same handful of validator companies. Currently, there are a limited number of companies in the world with the skills and capital to run top-notch validator companies.
|
||||
|
||||
Thus, if a protocol could unite a large number of those validator companies into a purpose-built consensus mechanism which is optimized for chain interoperability, that design would likely be both more performant and more secure than a network which was bootstrapped by a tokenomics model. Assuming the validators would be on board with this idea, how many could Wormhole realistically utilize?
|
||||
If a protocol could unite a large number of those validator companies into a purpose-built consensus mechanism that's optimized for chain interoperability, that design would likely be more performant and secure than a network bootstrapped by a tokenomics model. Assuming the validators would be on board, how many could Wormhole realistically utilize?
|
||||
|
||||
If Wormhole were to use threshold signatures, the answer would basically be 'as many as are willing to participate'. However, threshold signatures have spotty support across the blockchain world, this means it would be difficult and expensive to verify the signatures, which would limit scalability and chain agnosticism. Thus, a t-schnorr multisig is probably the best option as it is cheap and well supported, despite the fact that its verification costs increases linearly with the number of signatures included.
|
||||
If Wormhole were to use threshold signatures, the answer would basically be 'as many as are willing to participate.' However, threshold signatures have spotty support across the blockchain world, meaning it would be difficult and expensive to verify the signatures, ultimately limiting scalability and chain agnosticism. Thus, a t-schnorr multisig presents itself as the best option: cheap and well supported, despite the fact that its verification costs increases linearly with the number of signatures included.
|
||||
|
||||
So, with all these things considered, about 19 seems to be the maximum number and a good tradeoff. While it's less ideal than 2000, it's a lot more than most protocols have. 2000 would be infeasible to verify on-chain, and there are not even 2000 top-notch validators in the world today. If 2/3 of the signatures are needed for consensus, then 13 signatures need to be verified on-chain, which remains reasonable from a gas-cost perspective.
|
||||
All these things considered, 19 seems to be the maximum number and a good tradeoff. If 2/3 of the signatures are needed for consensus, then 13 signatures need to be verified on-chain, which remains reasonable from a gas-cost perspective.
|
||||
|
||||
Furthermore, rather than securing the network with tokenomics, it is better to initially secure the network by involving robust companies which are heavily invested in the success of De-Fi as a whole. The 19 Guardians are not just anonymous nobodies running their validators out of a basement. They are many of the largest and widely-known validator companies in cryptocurrency. The current Guardians can be viewed [here](https://wormholenetwork.com/network/)
|
||||
Rather than securing the network with tokenomics, it is better to initially secure the network by involving robust companies which are heavily invested in the success of De-Fi as a whole. The 19 Guardians are not anonymous or small--they are many of the largest and most widely-known validator companies in cryptocurrency. The current list of Guardians can be viewed [here](https://wormholenetwork.com/network/)
|
||||
|
||||
Putting this all together, we end up with 19 Guardians, each with an equal stake, joined in a purpose-built Proof of Authority consensus mechanism. As threshold signatures become better supported, the guardian set can expand, and once ZKPs are ubiquitous, the Guardian Network will become fully trustless.
|
||||
That's how we end up with the network of 19 Guardians, each with an equal stake and joined in a purpose-built Proof of Authority consensus mechanism. As threshold signatures become better supported, the Guardian set can expand, and once ZKPs are ubiquitous, the Guardian Network will become fully trustless.
|
||||
|
||||
Now that we have Decentralization laid out, the remaining elements fall into place.
|
||||
With our perspective on Decentralization laid out, the remaining elements fall into place.
|
||||
|
||||
## Modularity
|
||||
|
||||
Because the Guardian Network is robust and trustworthy by itself, there is no need for components like the relayer to contribute to the security model. Thus, Wormhole is able to have simple components which are very good at the one thing they do. The Guardians only need to verify on-chain activity and produce VAAs. Relayers only need to concern themselves with how to interact with blockchains and deliver messages.
|
||||
The Guardian Network is robust and trustworthy by itself, so there'ss no need for components like the relayer to contribute to the security model. That makes Wormhole able to have simple components that are very good at the one thing they do. That way, Guardians only need to verify on-chain activity and produce VAAs while Relayers only need to interact with blockchains and deliver messages.
|
||||
|
||||
The signing scheme of the VAAs can be changed without affecting downstream users. Multiple relay mechanisms can exist independently. xAssets can be implemented purely at the application layer. xDapps can utilize whatever components suit them.
|
||||
The signing scheme of the VAAs can be changed without affecting downstream users, and multiple relay mechanisms can exist independently. xAssets can be implemented purely at the application layer and xDapps can utilize whatever components suit them.
|
||||
|
||||
## Chain Agnosticism
|
||||
|
||||
Wormhole supports a wider range of ecosystems than any other interoperability protocol today. That is largely because it utilizes simple tech (t-schnorr signatures), an adaptable, heterogenous relayer model, and a robust validator network.
|
||||
Today, Wormhole supports a wider range of ecosystems than any other interoperability protocol because it uses simple tech (t-schnorr signatures), an adaptable, heterogenous relayer model, and a robust validator network.
|
||||
|
||||
Wormhole can expand to new ecosystems as quickly as a Core Contract can be developed for the smart contract runtime. Relayers don't need to be factored into the security model, they just need to be able to upload messages to the blockchain. The Guardians are able to observe every transaction on every chain, without taking shortcuts.
|
||||
Wormhole can expand to new ecosystems as quickly as a Core Contract can be developed for the smart contract runtime. Relayers don't need to be factored into the security model--they just need to be able to upload messages to the blockchain. The Guardians are able to observe every transaction on every chain, without taking shortcuts.
|
||||
|
||||
## Scalability
|
||||
|
||||
Wormhole scales quite well, as shown by Portal's ability to handle huge TVL and transaction volume, even during tumultuous events such as the UST depeg.
|
||||
Wormhole scales well, as demonstrated by Portal's ability to handle huge TVL and transaction volume--even during tumultuous events.
|
||||
|
||||
The requirements for running a Guardian are relatively heavy, as they need to run a full node for every single blockchain in the ecosystem. This is another reason why a limited number of robust validator companies are beneficial for this design.
|
||||
|
||||
However, once all the full nodes are running, the actual computation and network overheads of the Guardian Network are quite lightweight. As such, the performance of the blockchains themselves tends to be the bottleneck in Wormhole, rather than anything which happens inside the Guardian Network.
|
||||
However, once all the full nodes are running, the actual computation and network overheads of the Guardian Network become lightweight. The performance of the blockchains themselves tends to be the bottleneck in Wormhole, rather than anything happening inside the Guardian Network.
|
||||
|
||||
## Upgradability
|
||||
|
||||
|
|
|
|||
|
|
@ -1,69 +1,65 @@
|
|||
# Relayers
|
||||
|
||||
Relayers are a major part of the Wormhole Ecosystem. Where the Guardian Network is effectively the 'read' portion of interoperability, relayers are the 'write'.
|
||||
Relayers are a major part of the Wormhole Ecosystem. Where the Guardian Network is effectively the 'read' portion of interoperability, relayers are the 'write' portion.
|
||||
|
||||
The first thing of note is that unlike other interoperability protocols, Wormhole **does not have a required relaying methodology**.
|
||||
The definition of a _Relayer_ in the context of Wormhole is: Any process which delivers VAAs to a destination.
|
||||
|
||||
In most designs there is a dedicated relaying mechanism which operates inside the protocol's trust boundaries. This means that the relayer either has an adversarial relationship to the oracle, or the relayer has trust assumptions and contributes to the protocol's security model. Thus, relayers are usually a trusted party, are often also privileged, and you are forced to use the relayer model which is built into the protocol.
|
||||
Unlike other interoperability protocols, Wormhole **does not have a required relaying methodology**.
|
||||
|
||||
In most designs there is a dedicated relaying mechanism which operates inside the protocol's trust boundaries. This means that the relayer either has an adversarial relationship to the oracle, or the relayer has trust assumptions and contributes to the protocol's security model. Relayers are usually a trusted party, are often also privileged, and developers are typically forced to use the relayer model built into the protocol.
|
||||
|
||||
In Wormhole, relayers are neither trusted nor privileged. This means relayers **cannot jeopardize security, only liveness**. Because Wormhole is designed to have a firm trust boundary at the level of the VAA, relayers have exactly the same capabilities as any regular, untrusted blockchain user.
|
||||
|
||||
From this perspective, relayers are just dumb delivery trucks which deliver VAAs to their destination, and have no capacity to potentially tamper with the delivery outcome. VAAs either get delivered, or don't, which makes relayers analagous to the off-chain 'crank turners' of traditional Dapps.
|
||||
From this perspective, relayers are just delivery trucks that deliver VAAs to their destination, and have no capacity to tamper with the delivery outcome. VAAs either get delivered or don't, which makes relayers analagous to the off-chain 'crank turners' of traditional Dapps.
|
||||
|
||||
As a result of this design, Wormhole is able to fascilitate a variety of heterogenous relaying mechanisms, and the developer is able to choose whatever best suit their needs.
|
||||
|
||||
The definition of a _Relayer_ in the context of Wormhole is:
|
||||
|
||||
Any process which delivers VAAs to a destination
|
||||
As a result, Wormhole is able to facilitate a variety of heterogenous relaying mechanisms, and the developer is able to choose whatever best suit their needs.
|
||||
|
||||
Next, we'll go over a few of the most common relaying strategies.
|
||||
|
||||
## Client-side Relaying
|
||||
|
||||
Client side relaying is kind of a good tutorial case, as it's relatively straight forward.
|
||||
|
||||
All simple processes on Wormhole essentially boil down to a three step process:
|
||||
|
||||
1. Perform some action on chain A.
|
||||
1. Perform an action on chain A.
|
||||
2. Retrieve the resulting VAA from the Guardian Network.
|
||||
3. Perform some action on chain B using the VAA.
|
||||
3. Perform an action on chain B using the VAA.
|
||||
|
||||
Considering that the first step of this process is almost always initiated from a user-facing frontend such as a webpage or a wallet, it is possible to also perform steps 2 and 3 in the frontend as well. This is referred to as 'client-side relaying', and it has two major benefits:
|
||||
Considering that the first step of this process is almost always initiated from a user-facing frontend like a webpage or a wallet, it is possible to also perform steps 2 and 3 in the frontend as well. This is referred to as 'client-side relaying', and it has two major benefits:
|
||||
|
||||
- Low cost. Users pay exactly the transaction fee for the second transaction.
|
||||
- No backend relaying infrastructure.
|
||||
|
||||
For this reason, client-side relaying can be a tempting avenue to pursue, especially if you're just interested in getting an MVP running. However, client-side relaying has two notable drawbacks:
|
||||
That makes client-side relaying a tempting prospect, especially if you're just interested in getting an MVP running. However, client-side relaying also has two notable drawbacks:
|
||||
|
||||
- Users must sign all transactions required with their own wallet
|
||||
- Users must sign all transactions required with their own wallet.
|
||||
- Users must have funds to pay the transaction fees on every chain involved.
|
||||
|
||||
Overall, client-side relaying is a simple solution, but can make the user experience cumbersome. Thus, it's generally not recommended if your goal is a highly-polished user experience.
|
||||
Overall, client-side relaying is a simple solution, but can make the user experience cumbersome. It's generally not recommended if your goal is a highly-polished user experience.
|
||||
|
||||
## Specialized Relayers
|
||||
|
||||
Specialized Relayers solve the UX problems of client-side relayers by adding a backend component which can handle steps 2 and 3 on behalf of the user.
|
||||
Specialized relayers solve the UX problems of client-side relayers by adding a backend component which can handle steps 2 and 3 on behalf of the user.
|
||||
|
||||
In this model, relayers either listen directly to the Guardian Network via a spy (This is called **Spy Relaying**), or will simply provide a REST endpoint to accept a VAA which should be relayed (called **REST Relaying**). Once a relayer has the VAA, it simply performs any necessary off-chain calculations, and submits the VAA to the required destination.
|
||||
In this model, relayers either listen directly to the Guardian Network via a spy (This is called **Spy Relaying**), or will simply provide a REST endpoint to accept a VAA which should be relayed (called **REST Relaying**). Once a relayer has the VAA, it simply performs any necessary off-chain calculations and submits the VAA to the required destination.
|
||||
|
||||
An important consideration when developing a specialized relayer is that the relayer is still considered untrusted. VAAs are totally public, and can be submitted by anyone, so the off-chain relayer should not do any computation which is considered "trusted". However, doing things like deterministic data transforms, waiting for gas prices to drop, or various forms of 'batching' can be very useful cost-reduction strategies which do not impact security.
|
||||
An important consideration when developing a specialized relayer is that the relayer is still considered untrusted. VAAs are public and can be submitted by anyone, so the off-chain relayer should not do any computation which is considered "trusted." However, doing things like deterministic data transforms, waiting for gas prices to drop, or various forms of 'batching' can be very useful cost-reduction strategies that do not impact security.
|
||||
|
||||
Specialized Relayers have the following advantages:
|
||||
|
||||
- Simplify user experience
|
||||
- Allow off-chain calculations to be performed in the relayer, reducing gas costs.
|
||||
- Generally easy to develop
|
||||
- They simplify user experience
|
||||
- They allow off-chain calculations to be performed in the relayer, reducing gas costs
|
||||
- They are generally easy to develop
|
||||
|
||||
However, they also have a couple notable downsides
|
||||
|
||||
- Adds a backend relaying component which is responsible for liveness
|
||||
- Complicates fee-modeling, as relayers are responsible for paying target chain fees.
|
||||
- They add a backend relaying component which is responsible for liveness
|
||||
- They can complicate fee-modeling, as relayers are responsible for paying target chain fees.
|
||||
|
||||
Because relayers are responsible for liveness, they become another dependency component for the xDapp. If the relayers are all down, your application has an outage, similarly to how other dependencies such as the frontend, blockchain nodes, blockchains, third party APIs, etc, also can cause outages.
|
||||
Because relayers are responsible for liveness, they become another dependency component for the xDapp. If the relayers are all down, your application has an outage. This is similar to how dependencies like the frontend, blockchain nodes, blockchains, third party APIs, etc, can also cause outages.
|
||||
|
||||
To mitigate this, many relayers can be run in order to provide redundancy. It's also possible to design specialized relaying solutions which are entirely decentralized, such that there are a network of relayers which run based off economic incentives. However, creating a robust model for decentralized relaying is generally application-specific and somewhat complex.
|
||||
To mitigate this, multiple relayers can be run in order to provide redundancy. It's also possible to design specialized relaying solutions which are entirely decentralized, such that there are a network of relayers which run based off economic incentives. However, creating a robust model for decentralized relaying is generally application-specific and complex.
|
||||
|
||||
Due to specialized relayers being such a common solution,there is a reference implementation provided in the main Wormhole repository, which stands up the infrastructure needed to provide both a Spy and REST interface, and to interact with each blockchain in the ecosystem. If you plan to develop a specialized relayer, consider starting from the reference implementation, and add modifications as needed.
|
||||
Due to specialized relayers being such a common solution, there is a reference implementation provided in the main Wormhole repository which stands up the infrastructure needed to provide a Spy interface, a REST interface and the ability to interact with each blockchain in the ecosystem. If you plan to develop a specialized relayer, consider starting from the reference implementation and add modifications as needed.
|
||||
|
||||
# Generic Relayers
|
||||
|
||||
|
|
@ -71,19 +67,19 @@ _Note: this feature is not yet available in mainnet_
|
|||
|
||||
Because relaying is such an integral component to xDapps, Wormhole has built a protocol which allows developers to utilize a decentralized network of untrusted relayers to deliver their messages, removing the specialized relayer as an infrastructure responsibility.
|
||||
|
||||
In order to utilize the generic relayer network, developers must request delivery from the Wormhole Relay Ecosystem Contract, and must also implement a "receiveRelay" function in their contracts, which will be called by the relayer. Once a delivery has been requested, the VAA is guaranteed to be delivered within a certain timeframe. The specifics of this vary by blockchain and smart contract runtime.
|
||||
In order to utilize the generic relayer network, developers must request delivery from the Wormhole Relay Ecosystem Contract and must also implement a "receiveRelay" function in their contracts, which will be called by the relayer. Once a delivery has been requested, the VAA is guaranteed to be delivered within a certain timeframe. The specifics of this vary by blockchain and smart contract runtime.
|
||||
|
||||
Generic relayers have the following benefits:
|
||||
|
||||
- Simplified UX
|
||||
- No relayer infrastructure requirements for the developer
|
||||
- They feature simplified UX
|
||||
- There are no relayer infrastructure requirements for the developer
|
||||
|
||||
Along with the following potential downsides:
|
||||
And potential downsides:
|
||||
|
||||
- Require all calculations to be done on-chain
|
||||
- Less gas efficiency
|
||||
- May not be supported on all chains
|
||||
- They require all calculations to be done on-chain
|
||||
- They have less gas efficiency
|
||||
- They may not be supported on all chains
|
||||
|
||||
---
|
||||
|
||||
That's the main overview of how xData is emitted, verified, and delivered across the Wormhole ecosystem. In the next section we'll discuss the Portal Ecosystem contracts, which allow xAssets to be created and moved freely around the ecosystem.
|
||||
In the next section, we'll discuss the Portal Ecosystem contracts that allow xAssets to be created and moved freely around the ecosystem.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
# Portal
|
||||
# Portal xAsset Bridge
|
||||
|
||||
Portal is a set of ecosystem contracts which provision Wormhole's xAsset layer. These contracts allow tokens to be bridged around the Wormhole Ecosystem in a **path-independent** fashion, and in a manner easily composeable with other functions in the Wormhole ecosystem, such as Core-Layer messaging.
|
||||
Portal is a set of ecosystem contracts that provision Wormhole's xAsset layer. These contracts allow tokens to be bridged around the Wormhole Ecosystem in a **path-independent** fashion, and are easily composeable with other functions in the Wormhole ecosystem.
|
||||
|
||||
The Portal functions are a major focus of the [Wormhole Typescript SDK](https://www.npmjs.com/package/@certusone/wormhole-sdk). If you're looking to interact with Portal directly from a typescript client or backend, you should start there. This section will only provide a high-level overview of how to interact with the Portal contracts. If you'd prefer to look at code examples, they are provided in the **Portal Examples** section.
|
||||
This section provides a high-level overview of how to interact with the Portal contracts. If you're looking to interact with Portal directly from a typescript client or backend, you should start with the [Wormhole Typescript SDK](https://www.npmjs.com/package/@certusone/wormhole-sdk). If you'd prefer to look at code examples, they are provided in the **Portal Examples** section.
|
||||
|
||||
## Creating xAssets
|
||||
|
||||
xAssets always have an **origin chain**. This is the chain where the token is initially minted, via the standard of that chain (ERC-20, SPL, etc).
|
||||
xAssets always have an **origin chain**. This is where the token is initially minted via the standard of that chain (ERC-20, SPL, etc).
|
||||
|
||||
To begin converting this asset into an xAsset, an **attestation** must first be created. This is accomplished by simply calling the **attest** function on the Portal contract of the origin chain.
|
||||
To convert this asset into an xAsset, an **attestation** must first be created. To create an attestation, simply call the **attest** function on the Portal contract of the origin chain.
|
||||
|
||||
function attestToken(
|
||||
address tokenAddress,
|
||||
|
|
@ -25,7 +25,7 @@ The attestation VAA must then be submitted to the **createWrapped** function of
|
|||
|
||||
Calling this function will deploy a new contract for the token on the foreign chain, creating a **Wormhole-Wrapped Token**. The wrapped token will use the same symbol as the origin asset, and will append (Wormhole) to the end of the name.
|
||||
|
||||
These assets are all **fungible** with eachother. This means the wrapped token from any chain can be exchanged for the original token or any of the wrapped tokens from other chains.
|
||||
These assets are all **fungible** with each other. This means the Wormhole-wrapped token can be exchanged for the original token or wrapped tokens from other chains.
|
||||
|
||||
## Transferring Assets
|
||||
|
||||
|
|
@ -37,17 +37,17 @@ These assets are all **fungible** with eachother. This means the wrapped token f
|
|||
uint256 arbiterFee,
|
||||
uint32 nonce) returns (uint64 sequence)
|
||||
|
||||
Initiating a token transfer is a relatively straightforward affair. After the transfer is initiated, the Guardians will produce a transfer VAA once finality has been reached on the **source chain**. The VAA must then be relayed to the **target chain**.
|
||||
Initiating token transfers is a straightforward affair. Once the transfer is initiated, the Guardians will produce a transfer VAA when finality has been reached on the **source chain**. The VAA must then be relayed to the **target chain**.
|
||||
|
||||
All tokens managed by Portal are backed by the origin asset, and this allows for the tokens to be transferred in a path-independent fashion. Regardless of what chain the tokens are passed to, a 'double-wrapped' asset will never be created for a single backing asset. Additionally, because Portal is based purely on a wrapping model, there are no liquidity limitations.
|
||||
All tokens managed by Portal are backed by the origin asset, allowing tokens to be transferred in a path-independent fashion. Regardless of what chain the tokens are passed to, a 'double-wrapped' asset will never be created for a single backing asset. Additionally, there are no liquidity limitations.
|
||||
|
||||
## Contract-Controlled Transfers
|
||||
|
||||
Contract Controlled Transfers (CCTs) are a feature designed to allow xDapp contracts to easily perform Portal transfers. Contract controlled transfers are quite similar to simple transfers, but have two additional features:
|
||||
Basic transfers are intended to transfer tokens from one wallet to another, whereas Contract Controlled Transfers (CCTs) are meant to transfer tokens from one smart contract to another. If you're writing an xDapp, CCTs will likely be a large component.
|
||||
|
||||
- An arbitrary byte array can be appended to the transfer, which can be used to easily pass additional information to the recipient contract.
|
||||
CCTs allow xDapp contracts to easily perform Portal transfers. Contract controlled transfers are quite similar to simple transfers, but have two additional features:
|
||||
|
||||
- An arbitrary byte array can be appended to the transfer and can be used to easily pass additional information to the recipient contract.
|
||||
- The CCT VAA redeem can only be performed by the recipient contract, as opposed to basic transfers, which can be performed by any caller. This ensures that any additional operations which the contract wants to perform as part of the redeem transaction must be executed.
|
||||
|
||||
In short, basic transfers are intended to transfer tokens from one wallet to another, whereas CCTs are meant to transfer tokens from one smart contract to another. If you're writing an xDapp, you probably want to use CCTs for the most part.
|
||||
|
||||
In the next section. We'll discuss Wormchain, and some of the upcoming features it will enable.
|
||||
In the next section, we'll discuss Wormchain and some of the upcoming features it will enable.
|
||||
|
|
|
|||
|
|
@ -5,8 +5,12 @@ Wormchain is a purpose-built cosmos blockchain for the Wormhole ecosystem. It ha
|
|||
1. Provide a public and auditable mechanism for users to interact with the Guardian Network.
|
||||
2. Create a robust platform for on-chain infrastructure which would be infeasible to build elsewhere.
|
||||
|
||||
Wormchain is less relevant to xDapp developers than some other parts of the ecosystem, but it will become an increasingly important component as Wormhole matures and more features are added. Wormchain is built to provide things like:
|
||||
Wormchain is built to provide things like:
|
||||
|
||||
- Redundant security checks
|
||||
- Governance
|
||||
- Interactions with 'legacy' chains like Bitcoin
|
||||
|
||||
Wormchain is less relevant to xDapp developers than some other parts of the ecosystem, but it will become an increasingly important component as Wormhole matures and features are added.
|
||||
|
||||
In the next section, we'll get into the key concepts that underpin xDapp design.
|
||||
|
|
|
|||
Loading…
Reference in New Issue