certusone
/
xdapp-book
mirror of https://github.com/certusone/xdapp-book.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'mvp' of https://github.com/wormhole-foundation/xdapp-book into mvp

This commit is contained in:
spacemandev 2022-09-22 01:55:54 -05:00
parent f27e76a0f3 bf8b10f11b
commit 013e8c583e
59 changed files with 1303 additions and 384 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
src/SUMMARY.md
View File

@ -1,6 +1,6 @@
# Summary
[Introduction](./introduction/introduction.md)
- [Introduction](./introduction/introduction.md)
---
@ -22,7 +22,7 @@
- [VAA: Verified Action Approval](./wormhole/4_vaa.md)
- [Guardian Network](./wormhole/5_guardianNetwork.md)
- [Relayers](./wormhole/6_relayers.md)
- [Portal xAsset Bridge](./wormhole/7_portalTokenBridge.md)
- [xAsset Bridge](./wormhole/7_TokenBridge.md)
- [Wormchain](./wormhole/8_wormchain.md)
- [xDapp Design](./dapps/architecture/0_dappDesign.md)
@ -35,52 +35,50 @@
---
# xDapp Development
# Developing xDapps
- [Before You Start](./development/overview.md)
- [Wormhole Local Validator](./development/wormhole-local-validator.md)
- [Tilt Installation](./development/tilt/overview.md)
- [MacOS](./development/tilt/mac.md)
- [Linux](./development/tilt/linux.md)
- [Constants](./development/tilt/constants.md)
- [Project Scaffold](./development/scaffold/overview.md)
- [Sending Messages](./development/messages/sending/overview.md)
- [EVM](./development/messages/sending/evm.md)
- [Registering xDapps](./development/messages/registration/overview.md)
- [EVM](./development/messages/registration/evm.md)
- [Relaying Messages](./development/messages/relaying/overview.md)
- [Manual Relays]()
- [REST & Spy Relayer]()
- [Generic Relayers]()
- [Receving Messages](./development/messages/receiving/overview.md)
- [EVM](./development/messages/receiving/evm.md)
- [Projects](./projects/summary.md)
- [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]()
- [Environment Setup](./technical/env/environments.md)
---
- [Tilt (Devnet)](./technical/env/tilt.md)
- [Troubleshooting](./technical/env/troubleshooting.md)
- [Wormhole Local Validator](./technical/env/wlv.md)
- [Testnet](./technical/env/testnet.md)
- [Tooling](./technical/env/tooling.md)
# Portal Token Bridge
- [Contract Development]()
- [Portal](./development/portal/overview.md)
- [EVM](./technical/evm//overview.md)
- [Core Layer](./technical/evm/coreLayer.md)
- [xAsset Module](./technical/evm/xassetLayer.md)
- [NFT Module](./technical/evm/nftLayer.md)
- [Relayer Module](./technical/evm/relayer.md)
- [Best Practices](./technical/evm/bestPractices.md)
- [Solana]()
- [Cosmos]()
- [Algorand]()
- [Near]()
- [Aptos]()
- [Sui]()
- [Relayers](./technical/relayer/overview.md)
- [Generic Relayers](./technical/relayer/genericRelayer.md)
- [Specialized Relayers](./technical/relayer/pluginRelayers.md)
- [Wormhole Typescript SDK](./development/portal/overview.md)
- [EVM]()
- [Attesting](./development/portal/evm/attestingToken.md)
- [Transfer Tokens](./development/portal/evm/tokenTransfer.md)
- [Portal JS SDK](./development/portal/sdkjs/overview.md)
- [EVM to Solana Transfer](./development/portal/sdkjs/evm-solana-transfer.md)
- [Polygon to Oasis with Relayers](./development/portal/sdkjs/polygon-oasis-relayer.md)
- [Portal Payloads]()
---
# Other Resources
- [Reference]()
- [Tools](./reference/tools.md)
- [Github & Useful Links](./reference/github.md)
- [Deployed Contracts](./reference/contracts.md)
- [RPC Nodes](./reference/rpcnodes.md)
- [Glossary](./reference/glossary.md)
- [Tools](./reference/tools.md)
- [Github & Useful Links](./reference/github.md)
- [Deployed Contracts](./reference/contracts.md)
- [RPC Nodes](./reference/rpcnodes.md)

2
src/dapps/1_defiBasics.md
View File

@ -20,4 +20,6 @@ Two notable limitations are that blockchains have no access to off-chain data an
Blockchain developers are now aiming to solve these interoperability problems to create a unified ecosystem. In this new cross-chain ecosystem, people can move beyond being users of individual blockchains and take advantage of Web3 on a broader scale.
---
In the next section, we'll discuss the history and challenges of cross-chain interoperability, as well as introduce the role Wormhole plays in the future of this space.

14
src/dapps/2_crossChainInteroperability.md
View File

@ -2,9 +2,7 @@
Because blockchains are siloed by nature, individual cryptocurrencies being bound to their own chains has been a longtime limitation of blockchain technology. The first attempt at solving this problem was the creation of cryptocurrency exchanges like Coinbase and Binance. Today these are refered to as centralized exchanges (CEXs).
Centralized exchanges play an important role in cryptocurrency, but they are not a complete solution for cross-chain interoperability for two primary reasons: they're centralized, which is counterproductive to creating a decentralized platform, and they deal only with tokens.
As blockchains move toward being general-purpose computing platforms, interoperability will require data structures that are more complex than tokens and operations that are more sophisticated than transfers.
Centralized exchanges play an important role in cryptocurrency, but they are not a complete solution for cross-chain interoperability for two primary reasons: (1) they're centralized, which is counterproductive to creating a decentralized platform, and (2) they deal only with tokens.
To solve the centralization problems with CEXs, decentralized exchanges (DEXs) were created. A DEX operates inside a smart contract runtime and can be as decentralized as the blockchain it runs on. Unfortunately, a DEX is only able to utilize the tokens on its native blockchain. In order to obtain a token which is not native to that chain, the DEX must be used in combination with a **bridge**.
@ -17,16 +15,14 @@ There are some other essential things you should know about bridges before going
- Bridges are all mutually incompatible with eachother. Using multiple bridges just makes 'double wrapped' tokens.
- If tokens have become double wrapped after traversing multiple bridges or blockchains, there can be a complex unwrapping process to get back to the original token.
This explains how the ecosystem arrived at its current state--CEXs are a solution to siloed blockchains, DEXs are a simple response to CEXs, and DEXs have created a demand for bridges. Each solution in this timeline is an ad-hoc patch to the previous problem, and the current landscape of fractured liquidity, double wrapped tokens, isolated userbases and wallet incompatibilities is the result.
This explains how the ecosystem arrived at its current state -- CEXs are a solution to siloed blockchains, DEXs are a simple response to CEXs, and DEXs have created a demand for bridges. Each solution in this timeline is an ad-hoc patch to the previous problem, and the current landscape of fractured liquidity, double wrapped tokens, isolated userbases and wallet incompatibilities is the result.
Adding to this complexity are blockchains moving toward being general-purpose computing platforms. As such, interoperability will require data structures that are more complex than tokens and operations that are more sophisticated than transfers.
More ad-hoc solutions would only be short-term fixes for long-term problems, so it's critical to design new primatives and core infrastructure that will allow the next generation of decentralized applications to move beyond these lingering limitations.
This is why Wormhole exists. Wormhole proposes a new way of developing applications which leverages the strengths of each blockchain while mitigating the problems of the current ecosystem.
## Branded Terms
In some instances, Wormhole uses general terms for decentralized, cross-chain elements as branded verbiage. In most cases, the definition of the general term does not greatly differ from Wormhole definition, though Wormhole's definitions may be more narrow than general interpretations.
**xChain** - Across the Wormhole ecosystem, the full range of cross-blockchain interoperability is referred to under the term "xChain." "xChain" is the concept that houses other branded terms, like the Wormhole definitions of xAssets, xData and xApps.
---
Rethinking the next generation of decentralized applications means dethroning the token as the fundamental atomic unit of blockchains. We'll expand on this change in the next section.

12
src/dapps/3_xdataxassets.md
View File

@ -2,7 +2,7 @@
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.
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.
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.
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**.
@ -10,12 +10,6 @@ xData is akin to an xAsset in that it exists in its own layer independent of any
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.
## Branded Terms
---
In some instances, Wormhole uses general terms for decentralized, cross-chain elements as branded verbiage. In most cases, the definition of the general term does not greatly differ from Wormhole definition, though Wormhole's definitions may be more narrow than general interpretations.
**xData** - Wormhole defines xData as "data that exists in a layer outside of Layer 1 blockchains, which is accessible by all chains." The Wormhole definition of xData presents it as a branded element of xChain.
**xAssets** - Wormhole defines xAssets as a "chain-and-path agnostic token that exists on a layer outside the blockchain ecosystem, which can be used to conduct transactions on any blockchain." The Wormhole definition of xAssets presents itself as an element of xChain.
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.
Later in this document, we'll delve deeper into how Wormhole implements this [xData layer](../wormhole/3_coreLayerContracts.md) (also referred to as the 'Core' layer of Wormhole), but for now let's talk about how xData can be used to create xDapps.

8
src/dapps/4_whatIsanXdapp.md
View File

@ -4,16 +4,12 @@ The term **xDapp** is short for "Cross-Chain Decentralized Application". At firs
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 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.
Something we'll explore further in the upcoming xDapp Architecture chapter is the philosophy of [**Protocol-First Design**](./architecture/3_protocolDesign.md). 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 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** with multiple, specialized components working in unison to deliver a smooth, unified user experience across a variety of layer 1 ecosystems.
## Branded Terms
In some instances, Wormhole uses general terms for decentralized, cross-chain elements as branded verbiage. In most cases, the definition of the general term does not greatly differ from Wormhole definition, though Wormhole's definitions may be more narrow than general interpretations.
**xApp** - In the Wormhole xChain ecosystem, the term "xDapp" has been shortened to "xApp." These cross-chain applications are largely still decentralized, but for branding and simplicity purposes, the term "xApp" will be prioritized over "xDapp" when talking about Wormhole's xChain ecosystem.
---
In the next section, we'll summarize the concrete advantages which xDapps built on Wormhole have over traditional Dapps today.

4
src/dapps/5_advantages.md
View File

@ -8,11 +8,11 @@ Here are a few xDapp features that are making an impact across blockchain techno
- **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.
- **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 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.
- **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 Extensibility and Composeability** - xDapps can utilize anything across the ecosystem, including other xDapps, expanding upon the composability and openness of smart contracts.
- **Increased Extensibility and Composability** - xDapps can utilize anything across the ecosystem, including other xDapps, expanding upon the composability and openness of smart contracts.
- **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.

49
src/dapps/architecture/4_topology.md
View File

@ -1,16 +1,22 @@
# Topology
Topology describes how data flows through your application, and the responsibilities of each component. The primary decision to be made with regard to topology is mainly where your smart contracts will live, and what responsibilities each contract holds.
Topology describes how data flows through your application and defines the responsibilities of each component. In terms of overall xDapp topology, the primary decision is determining where your smart contracts will live and the responsibilities each contract will hold.
## Ultra-light Clients
![Ultra-light client](../../diagrams/images/ultralight.png "Ultra Light Clients")
![Ultra-light client](../../diagrams/images/ultralight_2.png "Ultra Light Clients")
Ultra-light Clients are often the best option when designing an MVP for your xDapp. The defining feature of an Ultra-light Client is that you are able to support users from every chain in the Wormhole ecosystem while **only having smart contracts on a single chain (!!!)**.
This works by deploying a single _hub_ contract (or just using an existing Dapp) onto the hub chain. You then add an entrypoint which supports _contract controlled transfers_ from the xAsset contracts on the hub chain. This allows your hub contract to receive both tokens **and instructions for what to do with them** from other chains in the Wormhole ecosystem.
xDapps with this structure work by having a hub chain that all application contract logic is deployed to and entrypoints which receive and send Wormhole messages to remote chains. The network of Wormhole contracts deployed on other chains across the ecosystem provide the rest of the heavy lifting to send messages across chains.
From there, the hub contract performs any necessary operations, and bridges any resultant tokens back to the wallet which iniated the contract controlled transfer. The only on-chain components are hub contract, and a relatively lightweight wrapper which allows the hub contract to send and receive tokens using the xAsset contracts. All other aspects of this topology are off-chain and untrusted. This pushes most of the development work out of smart contracts and into client-side typescript. This dramatically decreases smart contract risk, without altering the trust assumptions of your application.
You can think of the data flow across a xDapp with a Ultra-light Client as follows:
1. The end user's wallet interacts with Wormhole contracts on remote chain.
2. The Wormhole contracts on remote chain generate a VAA which is received by your xDapp contract on the hub chain.
3. Your xDapp contract on the hub chain performs all necessary operations.
4. Your xDapp contract interacts with Wormhole contracts on the hub chain.
5. The Wormhole contracts on hub chain generate a VAA which is sent back to the end user's wallet on the remote chain.
**_Advantages:_**
@ -20,20 +26,31 @@ From there, the hub contract performs any necessary operations, and bridges any
**_Disadvantages:_**
- Latency: Because all transactions have to bridge in and out of the hub chain, each transaction incurs the finality latency of both the remote and hub chain.
- Latency: Transactions incur latencies associated with bridging into and out of both the remote and hub chain.
- Transaction Fees: There are always a grand total of three transactions. Two on the remote chain, and one on the hub chain.
- Use cases: There is no place to perform trusted computation on the remote chain, so some use cases are more difficult to implement (or potentially not possible).
## Hub and Spoke
## Hub-and-Spoke
Hub and Spoke models are somewhat of a natural evolution of the ultra-light client. There is still a hub contract which handles all transactions, but there is now also a contract deployed to all the remote chains.
![Hub and Spoke](../../diagrams/images/hub_and_spoke.PNG "Hub and Spoke")
Advantages:
Hub and Spoke models can somewhat be thought of as the natural evolution of the ultra-light client. There is still a hub contract which handles all transactions, but there is now also a contract deployed to all the remote chains that is capable of performing some trusted computation.
You can think of the data flow across a Hub-and-Spoke system as follows:
1. The end user's wallet interacts with your (lightweight) remote contracts.
2. The remote contracts perform any necessary trusted computation.
3. The remote contracts use Wormhole to generate a VAA, which is consumed by the hub contract.
4. The hub contract performs all necessary operations.
5. The hub contract uses Wormhole to send a message back to the original remote contract.
6. The remote contract takes whatever action is needed to finish the process.
**_Advantages:_**
- Remote contracts are lightweight and don't carry large amounts of risk.
- Can perform trusted checks on the remote chain. (Such as validating wallet balance, or any other piece of blockchain state)
Disadvantages:
**_Disadvantages:_**
- Latency (same as ultra-light clients)
- Transaction Fees
@ -41,14 +58,18 @@ Disadvantages:
## Mesh
A Mesh topology is one where each chain implements the full logic for a process, such that each contract is a peer of other contracts in the trusted network and can act autonomously.
![Mesh](../../diagrams/images/mesh.PNG "Mesh")
Advantages:
Mesh topologies can somewhat be thought of as the next evolution of the Hub and Spoke model. There are now contracts capable of handling all transactions for an application are deployed on all supported chains. Each contract can be thought of as a peer of other contracts in the trusted network and can act autonomously.
This is historically the most popular methodology for going cross-chain. It's very attractive in ecosystems like EVM or Cosmos, where a single smart contract can simply be deployed across many different blockchains.
**_Advantages:_**
- Latency: Users can often perform their operation without waiting for other chains.
- Transaction Fees: Does not stack the transaction fees of multiple chains.
Disadvantages:
**_Disadvantages:_**
- Complexity: there are now quite a few contracts to manage, especially if they are implemented multiple times across different VMs.
- Data desync: because each blockchain acts independently, each chain will have independent state. This can open up unwanted arbitrage opportunities and other discrepancies.
@ -56,7 +77,9 @@ Disadvantages:
## Distributed
A distributed topology is one where different blockchains have different responsibilities.
![Distributed](../../diagrams/images/distributed.PNG "Distributed")
Distributed topologies can somewhat be thought of as the next evolution of the Mesh model. Instead of contracts that are capable of handling all transactions for an application on all supported chain, applications are broken up into separate responsibilities (i.e. data storage, user interaction, asset custody, governance) and deployed to different blockchains.
Advantages:

60
src/dapps/architecture/5_relayers.md
View File

@ -1,30 +1,28 @@
# Relayers
In Chapter 2, we discussed the [general concepts associated with relayers in the Wormhole ecosystem](../../wormhole/6_relayers.md). In this section, we'll elaborate on what considerations need to be taken into account when using relayers for your xDapp.
In Chapter 2, we discussed the [general concepts associated with relayers in the Wormhole ecosystem](../../wormhole/6_relayers.md). In this section, we'll elaborate on the considerations that should be accounted for when using relayers in your xDapp.
## Fundamentals
The most important thing to remember about relayers is that they are _untrusted_. This means you don't have to trust them, but it also means you can't trust them. This is true of both generic and specialized relayers.
It's important to remember that relayers are untrusted. This means you don't have to trust them--but it also means you can't trust them. This is true of both generic and specialized relayers.
Let's dive into a little more detail about _why_ relayers are untrusted, and what this means for you when designing a protocol.
Let's dive into a little more detail about why relayers are untrusted and what this means for you.
A few key properties of VAAs are that they:
A few key properties of VAAs:
- are publicly emitted from the Guardian Network
- They are publicly emitted from the Guardian Network.
- They need to be signed by the Guardian Network to be considered authentic.
- They can be verified as authentic by anyone and any Wormhole Core Contract.
- need to be signed by the Guardian Network to be considered authentic
Relayers are untrusted as an inherent consequence of these properties. Anyone can pick up a VAA and deliver it anywhere, but no one can alter the content of the VAA without invalidating the signatures.
- can be verified as authentic by _any_ Wormhole Core Contract they are brought to _by anyone_.
So, when writing your contracts, it's incredibly important to only trust information which is either inside your contract or inside a VAA. If you trust information provided by a relayer, you are opening yourself up to untrusted input attacks.
Relayers are untrusted as an inherent consequence of these properties. Anyone can pick up a VAA and deliver it anywhere they feel like, however, no one can alter the content of the VAA without invalidating the signatures.
The easiest and most secure way to interact with relayers then is to only accept the VAA as input. If the relayer can't provide any additional args, then there's no way for them to provide untrusted input.
So, when writing your contracts, it's incredibly important to only trust information which is either **inside your contract** or **inside a VAA**. If you trust information provided by a relayer, you are opening yourself up to untrusted input attacks.
More advanced strategies involve having the relayer perform untrusted off-chain computation which is passed into the destination contract. These strategies can optimize gas costs, but can also create attack vectors if not used correctly.
The easiest and most secure way to interact with relayers then is to _only accept the VAA as input_. If the relayer can't provide any additional args, then there's no way for them to provide untrusted input.
There are more advanced strategies whereby the relayer performs **untrusted** off-chain computation which is passed into the destination contract. These strategies can optimize gas costs, but must be used carefully, as they can create attack vectors if not used correctly.
With this in mind, relayer design is mostly a matter of structuring the messages in your protocol in a manner such that there is a single, deterministic way that they can be processed. In a well designed protocol, relayers have a 'correct' implementation.
With this in mind, relayer design becomes a matter of structuring the messages in your protocol such that there is a single, deterministic way that they can be processed. In a well designed protocol, relayers have a 'correct' implementation.
Relayers are conceptually quite similar to "crank turner" processes used elsewhere in blockchain, in that there is only a single action which can be taken (pulling the crank), and their sole responsibility is to initiate this action and pay for the costs.
@ -32,42 +30,42 @@ Relayers are conceptually quite similar to "crank turner" processes used elsewhe
## Generic Relayers
Generic Relayers are a decentralized relayer network which can deliver arbitrary VAAs, so long as the recipient contract is conformant with the generic relayer API.
Generic relayers are a decentralized relayer network which can deliver arbitrary VAAs as long as the recipient contract conforms with the generic relayer API.
### Advantages:
**_Advantages:_**
- Purely done on-chain. No need to develop, host, or maintain relayers
- Generic relayers are done purely on-chain, so there's no need to develop, host or maintain relayers.
### Disadvantages:
**_Disadvantages:_**
- Less room for optimization via features like conditional delivery, batching, off-chain calculations, etc.
- There's less room for optimization via features like conditional delivery, batching, off-chain calculations, etc.
---
## Specialized Relayers
Specialized Relayers are relayers which are purpose-built to relay messages for a certain application.
Specialized Relayers are relayers that are purpose-built to relay messages for a certain application. In the future, there may be ways to customize generic relayers such that they will gain the advantages of today's specialized relayers.
### Advantages:
**_Advantages:_**
- Can perform off-chain untrusted computation
- Highly customizeable. Can perform batching, conditional delivery, multi-chain deliveries, etc.
- Can home-roll an incentive structure
- Specialized relayers can perform off-chain untrusted computation.
- They are highly customizeable and can perform batching, conditional delivery, multi-chain deliveries, etc.
- Can home-roll an incentive structure.
### Disadvantages
**_Disadvantages_**
- Requires development work, and requires relayer hosting
- Requires development work and relayer hosting.
In the future, there may be ways to customize generic relayers such that they will gain the advantages of today's specialized relayers.
---
### Relayer Incentives
Relayers have to cover the costs of executing the downstream transactions resulting from the original 'source' transaction. Unless the relayers are running at a loss, there must be a mechanism for reimbursing the relayer in exchange for message delivery.
There are tons of strategies here, and the 'best' strategy for an application is often dependent on the specifics of that application. However, a few of the most common strategies are:
There are many strategies for reimbursement, and the 'best' strategy for an application is often dependent on the specifics of that application. However, a few of the most common strategies are:
- pay the relayer with a potion of the tokens being sent cross-chain
- collect a safe amount of gas money from the end user prior to performing any actions
- 'lazy' relaying, where relaying might only become profitable in certain, potentially rare, market conditions
- Pay the relayer with a potion of the tokens being sent cross-chain.
- Collect a safe amount of gas money from the end user prior to performing any actions.
- 'Lazy' relaying, where relaying might only be profitable in certain, potentially rare, market conditions.
Generic relayers have an incentive model built in to the network, so you do not need to design an incentive structure when using them.

12
src/development/messages/relaying/overview.md
View File

@ -2,14 +2,14 @@
Relaying Messages can be done one of three ways:
1. Manual Relaying
**_Manual Relaying_**
Manual Relaying is usally done on the front end. Manual relyaing requires the front end to fetch the VAA it just created and then submit on the target chain. This means the user ends up paying for the gas fee and has to go through the additional step to submit the tx on the target chain.
Manual relaying is usally done on the front end. Manual relaying requires the front end to fetch the VAA it just created and then submit on the target chain. This means the user ends up paying for the gas fee and has to go through the additional step to submit the tx on the target chain.
2. Protocol Specific Relayers
**_Protocol-Specific Relayers_**
Protocols and Apps can run their own relayers, listening to messages as they are created by the Core Bridge and submitting them to their application on the target chain. This is the ideal user experience but requires more work from the developer.
Protocols and apps can run their own relayers that listen to messages as they are created by the Core Bridge and submit them to their application on the target chain. This offers the ideal user experience, but requires more work from the developer.
3. Generic Relayers
**_Generic Relayers_**
Generic Relayers can pick up any app or protocol's messages and submit them to the target chain for a fee. This is the ideal developer and user experience, but is still being developed.
Generic relayers can pick up any app or protocol's messages and submit them to the target chain for a fee. This is the ideal developer and user experience, but is still evolving.

25
src/development/overview.md
View File

@ -1,23 +1,24 @@
# Wormhole Development Overview
The general flow for a cross-chain message goes from an application deployed to chain A, to the Wormhole contract on chain A, to the Guardian network, then submitted to chain B.
Cross-chain messages typically flow from an application deployed to a blockchain to the Wormhole contract on that same chain, then to the Guardian network before finally being submitted to a host chain.
To get started and simulate this flow locally, you'll need a local environment to test your xdapp code. To test, we need to be able to deploy some chains, deploy the Wormhole contracts to these chains, and then run at least one Wormhole validator to pick up messages.
To test your xDapp code, you'll need a local environment to simulate this process. Your local environment needs to be able to deploy multiple chains, deploy Wormhole contracts to those chains and run at least one Wormhole validator to pick up messages.
Later, we can introduce a relayer to automatically submit messages, though that's currently supported for Mainnet Token Bridge native and stable coin transfers only. Developers currently have to use either a manual relayer method or an app-sepecific relayer (more on that in the Relayer section).
Later, we can introduce a relayer to automatically submit messages, though this is currently supported for Mainnet Token Bridge native and stable coin transfers only. Currently, developers need to use either a manual relayer method or an app-sepecific relayer. You can find more details on relayers in the Relayers section of this guide.
Before we setup an xdapp project, we'll need to choose a local environment to run the Wormhole Guardian Network. We can use either Wormhole Local Validator or Tilt.
Before we set up an xDapp project, we'll need to choose a local environment to run the Wormhole Guardian Network. Our best options are either Wormhole Local Validator or Tilt.
- [Wormhole Local Validator](./wormhole-local-validator.md): This is the simplest custom environment. It's BYOB (Bring your own Blockchain), where you can run your own local validator nodes and connect them to a single Guardian running on docker. Initial setup can take upwards of 500 seconds, but after the image is built, bringing it up and down is usually <1 minute. This environment requires installing the software for the validator nodes locally on your computer or somewhere to run them.
- [Tilt](./tilt/overview.md): A full-fledged Kubernetes deployment of *every* chain connected to Wormhole, along with a Guardian node. Usually takes 30 min to spin up fully, but comes with all chains running out of the box.
- [Wormhole Local Validator](./wormhole-local-validator.md): This is the simplest custom environment. It's BYOB (Bring your own Blockchain) with the ability to run your own local validator nodes and connect them to a single Guardian running on docker. Initial setup can take upwards of 500 seconds, but after the image is built, bringing it up and down should take less than a minute. This environment requires installing the software for the validator nodes locally.
- [Tilt](./tilt/overview.md): A full-fledged Kubernetes deployment of every chain connected to Wormhole, along with a Guardian node. Usually takes 30 min to spin up fully, but comes with all chains running out of the box.
### First Steps
To get started, first clone the a local host environment (WLV or Tilt), then proceed to the first project, the [evm-messenger](../projects/evm-messenger/overview.md).
### Testnet
If you want to test on the various test and devnets of existing connected chains, there's a single Guardian node watching for transactions on various test networks. You can find the contracts [here](../reference/contracts.md) and the rpc node [here](../reference/rpcnodes.md).
If you want to test on the various test and devnets of existing connected chains, there's a single Guardian node watching for transactions on various test networks. You can find the contracts at [../reference/contracts.md](../reference/contracts.md) and the rpc node at [../reference/rpcnodes.md](../reference/rpcnodes.md).
Because testnet only has a single Guardian, there's a small chance that your VAAs will not be processed. This rate is *not* indiciative of performance on mainnet, where there are 19 Guardians watching for transactions.
Because testnet only has a single Guardian, there's a small chance that your VAAs will not be processed. This rate is not indiciative of performance on mainnet, where there are 19 Guardians watching for transactions.
### Mainnet
When you're ready to deploy to mainnet, you can find the mainnet contracts [here](../reference/contracts.md) and the mainnet rpc nodes [here](../reference/rpcnodes.md).
## Next Steps
To get started, first clone the a local host environment (WLV or Tilt), then proceed to the first project, the [evm-messenger](../projects/evm-messenger/overview.md).
When you're ready to deploy to mainnet, you can find the mainnet contracts at [../reference/contracts.md](../reference/contracts.md) and the mainnet rpc nodes at [../reference/rpcnodes.md](../reference/rpcnodes.md).

20
src/development/portal/overview.md
View File

@ -1,22 +1,24 @@
# Portal Token Bridge Transfers
# Portal Token Bridge
Portal Token Bridge is one of the biggest applications built on Wormhole. It uses structured payloads to transfer tokens and NFTs from one wallet to another.
## Attesting a Token
Before a token can be transferred, the token need to be *attested* to another chain. To attest a token, you first create a AssetMeta VAA by calling the `attest()` function on Token Bridge. Then you take the VAA over to the receipient chain, where you call `createWrapped()` which deploys a wrapped version of the Token.
Before a token can be transferred, the token need to be attested to another chain. To attest a token, you first create a AssetMeta VAA by calling the `attest()` function on Token Bridge. Then, take the VAA over to the receipient chain where you'll call `createWrapped()` which deploys a wrapped version of the token.
This only needs to happen *once* per payload, and trying to attest a token a second time will simply result in the address of the already-created Wrapped Token Address.
This only needs to happen once per payload, and trying to attest a token a second time will simply result in the address of the already-created Wrapped Token Address.
## Transfering Tokens
To transfer tokens, the payer of tokens first authorizes the Token Bridge contract to move the tokens on their behalf, then locks them up with the Token Bridge, which then emits a VAA. This VAA can then be submitted on target chain's Token Bridge's `completeTransfer()` to mint the wrapped version of the Token.
To transfer tokens, the payer of tokens first authorizes the Token Bridge contract to move the tokens on their behalf, then locks them up with the Token Bridge, which emits a VAA. This VAA can then be submitted on target chain Token Bridge's `completeTransfer()` to mint the wrapped version of the token.
When transfering tokens from Chain A to B and beyond, the token is only "wrapped" once, as every time it's attested, it's always from the chain the token is natively located on. If the token being transferred is native to the chain it's being transfered to, you'll receive the original token back instread of a wrapped version.
When transfering tokens from Chain A to B and beyond, the token is only "wrapped" once, as every time it's attested, it's always from the chain where the token is natively located. If the token being transferred is native to the chain it's being transfered to, you'll receive the original token back instread of a wrapped version.
There are typically two functions for transfer: `transfer()` and `transferNative()`. This is because native currencies of most blockchains (ETH on Ethereum, SOL on Solana, etc) don't follow the Token spec of that chain, so to transfer native currencies, we wrap them first into a tokenized version and then transfer.
There are typically two functions for transfer: `transfer()` and `transferNative()`. This is because native currencies of most blockchains (ETH on Ethereum, SOL on Solana, etc) don't follow the token spec of that chain, so to transfer native currencies, we wrap them first into a tokenized version and then transfer.
For transfers, there's also an arbiterFee you can set. If this fee is set, when `completeTransfer()` is called, that amount of tokens are withheld from the release of tokens on the target chain and instead given to the submitter of the message (for example, a relayer). This allows third party to submit transactions on your behalf, for a fee.
For transfers, there's also an arbiterFee you can set. If this fee is set, when `completeTransfer()` is called, that amount of tokens are withheld from the release of tokens on the target chain and instead given to the submitter of the message (for example, a relayer). This allows a third party to submit transactions on your behalf, for a fee.
## Transfering with a Payload
Transfering with a Payload is much like transfering normal tokens, with two major differences.
Transfering with a Payload is much like transfering normal tokens, with two major differences:
First, as the name implies, you can attach a bytes payload to the transfer message. Secondly, the `completeTransfer()` function for Transfer with Payload can *only* be called by the receipient of that VAA. This means the flow is slightly different; instead of the user calling the `completeTransfer()` function on the Token Bridge, they call a function on the application they are interacting with which will check the payload, do any state changes it needs to make and then call `completeTransfer()` on Token Bridge to mint tokens to itself.
First, as the name implies, you can attach a bytes payload to the transfer message.
Secondly, the `completeTransfer()` function for Transfer with Payload can *only* be called by the receipient of that VAA. This means the flow is slightly different--instead of the user calling the `completeTransfer()` function on the Token Bridge, they call a function on the application they are interacting with which will check the payload, finalize any state changes and then call `completeTransfer()` on Token Bridge to mint tokens to itself.

14
src/development/scaffold/overview.md
View File

@ -1,21 +1,19 @@
# xDapp Scaffold
To help you get started with cross chain development, we've provided a template project in `projects/xdapp-starter`. All the sample projects will be made using this template, so check them out if you want to get a feel for how the various modules interact with each other.
To help you get started with cross-chain development, we've provided a template project in `projects/xdapp-starter`. All sample projects will be made using this template, so check them out if you want to get a feel for how various modules interact with each other.
The template uses npm workspaces to setup a main project with subdirectories for each chain you want to interact with. This allows you to initialize each subdirectory using whatever scaffolding tool you want for each individual chain, and orchestration code in a common directory.
The template uses npm workspaces to setup a main project with subdirectories for each supported chain. This allows you to initialize each subdirectory using any scaffolding tool for each individual chain along with orchestration code in a common directory.
Let's break down what's in the `xdapp-starter` project:
What's in the `xdapp-starter` project:
### chains/
- This folder contains the subdirectories for chain specific code. For example, I might use the `anchor` tool to `anchor init solana-project` within the chains/ directory.
This folder contains the subdirectories for chain-specific code. For example, you might use the `anchor` tool to `anchor init solana-project` within the chains/ directory.
### handlers/
The handlers folder contains the js client code to deal with each chain's specific needs. They expose a common API that we can consume in `starter.js` for code cleanliness.
They all take in a context object that's made up of the
The handlers/ folder contains the js client code to deal with each chain's specific needs. They expose a common API that we can consume in `starter.js` for code cleanliness.
### orchestrator.js
This file parses command line args and filters calls to chain management handlers.
### xdapp.config.json
The config file contains all the information about the network rpc nodes, accounts, and other constants used to communicate with contracts deployed to the selected chains.
The config file contains all the information about the network rpc nodes, accounts, and other constants used to communicate with contracts deployed to the selected chains.

6
src/development/tilt/constants.md
View File

@ -1,7 +1,5 @@
# Contracts and Accounts
The devnet environment deploys the Wormhole and Portal contracts to each of the chains at the same addresses every time.
It also funds specific wallets with funds.
The devnet environment deploys the Wormhole and Portal contracts to each of the chains at the same addresses every time. It also provides specific wallets with funds.
## Tilt
## Guardian
@ -16,4 +14,4 @@ It also funds specific wallets with funds.
## Algorand
- RPC Port:
## Terra
- RPC Port:
- RPC Port:

21
src/development/tilt/linux.md
View File

@ -1,7 +1,7 @@
# Linux Devnet Setup
### Experimental Setup Script
There's an experimental one command setup script that should install dependencies for you on Linux and configure everything properly. This is only recommended if you're running headless Linux and unable to use Docker Desktop, as with Docker Desktop you don't need `minikube` and can just enable Kubernetes from Docker.
There's an experimental single command setup script that should install dependencies for you on Linux and configure everything properly. This is only recommended if you're running headless Linux and unable to use Docker Desktop, as you can enable Kubernetes from Docker.
```sh
curl $URL | sh install_linux.sh
@ -12,25 +12,30 @@ cd wormhole/
## Regular Setup
### 1. Install Go
```sh
wget https://go.dev/dl/go1.18.1.linux-amd64.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.18.1.linux-amd64.tar.gz
```
### 2. Install Docker
If you're using Linux with a window manager, consider getting Docker Desktop instead of the following command. It comes with Kubernetes built in and you won't need to download `minikube`. It's recommended to have at least 4 CPUs and 16GB RAM dedicated to Docker.
Also make sure that you set up docker as a NON ROOT USER!
Also, make absolutely sure that you set up Docker as a non-root user.
[https://docs.docker.com/engine/install/ubuntu/#installation-methods](https://docs.docker.com/engine/install/ubuntu/#installation-methods)
### 3. (Docker Desktop Install)
Enable Kubernetes by going into Settings > Kubernetes
### 3. (Non Docker Desktop)
Install [`minikube`](https://minikube.sigs.k8s.io/docs/start/)
Configure minikube
Install [`minikube`](https://minikube.sigs.k8s.io/docs/start/).
Configure minikube:
```
minikube start --driver=docker --kubernetes-version=v1.23.3 --cpus=4 --memory=14G --disk-size=10G --namespace=wormhole
```
@ -39,7 +44,8 @@ If you reboot your VM you'll need to run the `minikube start` command again befo
### 4. Install Tilt
Install tilt by copy pasting this into the Terminal
Install Tilt by copy pasting this into the Terminal:
```sh
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash
```
@ -50,13 +56,14 @@ curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/instal
git clone --branch dev.v2 https://github.com/certusone/wormhole.git
```
If you're running tilt on your machine
If you're running Tilt on your machine:
```sh
cd wormhole/
tilt up
```
If you're running tilt in a VM, we need to pass in some extra flags to enable Tilt to listen to incoming traffic from external addresses.
If you're running Tilt in a VM, you'll need to pass in some extra flags to enable Tilt to listen to incoming traffic from external addresses:
```sh
cd wormhole

3
src/development/tilt/mac.md
View File

@ -5,8 +5,8 @@ You'll need to have `homebrew` on your system if you don't already. You can grab
```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
## Install Go
## Install Go
```sh
brew install go
```
@ -24,7 +24,6 @@ brew install tilt
```
## Clone Wormhole Repo and Start Tilt
```sh
git clone --branch dev.v2 https://github.com/certusone/wormhole.git
```

22
src/development/tilt/overview.md
View File

@ -1,18 +1,18 @@
# Tilt Development Environment
For a quicker development cycle, specially when developing your own blockchain programs that interact with Wormhole or Portal contracts, consider setting up the Tilt Devnet Environment.
For a faster development cycle, especially when developing blockchain programs that interact with Wormhole or Portal contracts, consider setting up the Tilt Devnet Environment.
Tilt is a kubernetes and docker orchestration tool that will spin up all the Wormhole supported chains in containers, alongside a Guardian node that will observe and store VAAs.
Tilt is a Kubernetes and Docker orchestration tool that will spin up all the Wormhole supported chains in containers, alongside a Guardian node that will observe and store VAAs.
This devnet environment can be set up on your computer or in a Linux VM that has at least 4 CPU cores and 16GB of RAM.
If you do decide to host the devnet in a remote VM, remember to pass in the host and webHost flags during the tilt up step and allow incoming traffic on your VM to be able to access the various RPC endpoints on the Pods.
If you do decide to host the devnet in a remote VM, remember to pass in the host and webHost flags during the tilt up step and allow incoming traffic on your VM to be able to access the various RPC endpoints on the pods.
```sh
tilt up --host=0.0.0.0 -- --webHost=0.0.0.0
```
While the exact commands for each environment might differ, the basic setup process for tilt is the following:
While the exact commands for each environment might differ, the basic setup process for Tilt is the following:
1. Install Go
2. Install Docker Desktop (Or Docker CE)
@ -22,15 +22,15 @@ While the exact commands for each environment might differ, the basic setup proc
## FAQ
### Where are Fantom/Celo/Polygon/...(insert other EVM chains)
For all chains that support EVM the smart contract development environment is effectively the same. For changes in gas costs and transaction times, consider testing contract logic on devnet and then using testnet environments to get chain specific answers.
### Where are Fantom/Celo/Polygon/other EVM chains?
For all chains that support EVM, the smart contract development environment is effectively the same. For changes in gas costs and transaction times, consider testing contract logic on devnet and then using testnet environments to get chain-specific answers.
### Solana is taking forever!
Unfortunately, due to Solana's architecture, it often takes 25-40min to build the Solana pod. Consider increasing CPU cores assigned to devnet for a faster build.
### Solana is taking forever
Due to Solana's architecture, it often takes 25-40min to build the Solana pod. Consider increasing CPU cores assigned to devnet for a faster build.
### Solana program deploy doesn't work
Kubernetes doesn't currently allow port forwarding for UDP ports, which is what Solana uses for `solana program deploy`. Instead, we recommend using [Solana Deployer](https://github.com/acheroncrypto/solana-deployer). Not only does this deploy programs over regular RPC thus bypassing UDP port requirements, it's also much faster than `solana program deploy`.
### Solana program deploy doesn't work
Kubernetes doesn't currently allow port forwarding for UDP ports, which is what Solana uses for `solana program deploy`. Instead, we recommend using [Solana Deployer](https://github.com/acheroncrypto/solana-deployer). Not only does this deploy programs over regular RPC (thus bypassing UDP port requirements), it's also much faster than `solana program deploy`.
### Reset state for a pod
If you want to quickly iterate and don't want to bring tilt down and back up, you can reset state for a pod by clicking the 🔄 button next to the pod name in Tilt UI.
If you want to quickly iterate and don't want to bring Tilt down and back up, you can reset state for a pod by clicking the 🔄 button next to the pod name in Tilt UI.

4
src/development/wormhole-local-validator.md
View File

@ -1,5 +1,5 @@
# Wormhole Local Validator
The Wormhole Local Validator is available [here](https://github.com/certusone/xdapp-book/tree/main/projects/wormhole-local-validator). Along with the Wormhole Local Validator, this also contains code to spin up EVM and Solana local validators, as well as deployment code to add Wormhole contracts to those new chains.
[The Wormhole Local Validator is available here](https://github.com/certusone/xdapp-book/tree/main/projects/wormhole-local-validator). Along with the Wormhole Local Validator, this link also contains code to spin up EVM and Solana local validators along with deployment code to add Wormhole contracts to those new chains.
## Dependencies
You will need Docker; if you're developing on your computer you should get [Docker Desktop](https://docs.docker.com/get-docker/), but if you're in a headless VM, install [Docker Engine](https://docs.docker.com/engine/). Make sure to have Docker running before you run any of the following commands.
@ -23,4 +23,4 @@ Simply run `npm run wormhole`, which will pull and run the Wormhole Guardian doc
### FAQ & Common Problems
- Anvil isn't working
While we recommend Foundry's Forge tool for compiling and deploying code elsewhere in these docs, we *do not* at this time recommend using anvil for guardiand; this is because guardiand is spec'd against go-ethereum, and anvil is out of spec for how it reports block headers (non left padding to normalize length), which means go-ethereum reacts abnormally and can't read anvil headers.
While we recommend Foundry's Forge tool for compiling and deploying code elsewhere in these docs, we do not at this time recommend using anvil for guardiand; this is because guardiand is spec'd against go-ethereum, and anvil is out of spec for how it reports block headers (non left padding to normalize length), which means go-ethereum reacts abnormally and can't read anvil headers.

BIN
src/diagrams/images/architecture-2022-01-02-1935.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 101 KiB

BIN
src/diagrams/images/architecture.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 105 KiB

BIN
src/diagrams/images/distributed.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

BIN
src/diagrams/images/hub_and_spoke.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 62 KiB

BIN
src/diagrams/images/mesh.PNG Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 74 KiB

BIN
src/diagrams/images/ultralight_2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB

16
src/projects/evm-messenger/messenger.md
View File

@ -1,7 +1,7 @@
# Messenger.sol
Messenger.sol is an application contract on EVM capable of communicating with the Wormhole core bridge.
Messenger.sol is an application contract on EVM capable of communicating with the Wormhole Core Bridge.
Start by 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 an interfaced link to it.
```solidity
//SPDX-License-Identifier: Unlicense
@ -26,7 +26,7 @@ contract Messenger {
```
## Constructor
This sets 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 other chains.
```solidity
@ -39,10 +39,10 @@ constructor(){
## SendMsg
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
- Payload: the bytes payload
- Confirmations: the number of blocks the guardians should wait before signing this VAA. For low security applications, this number can be low, but if you're on a chain that often reorgs a high number of blocks (like Polygon) you might want to set this number high enough to ensure your transaction from the source chain doesn't get lost after the guardians sign it.
The `publishMessage()` function of the core_bridge takes three arguments:
- Nonce: A number to uniquely identify this message, used to make sure that the target chain doesn't double process the same message
- Payload: The bytes payload
- Confirmations: The number of blocks the Guardians should wait before signing this VAA. For low security applications, this number can be low, but if you're on a chain that often reorgs a high number of blocks (like Polygon) you might want to set this number high enough to ensure your transaction from the source chain doesn't get lost after the Guardians sign it.
```solidity
function sendMsg(bytes memory str) public returns (uint64 sequence) {
@ -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 Guardians, 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

8
src/projects/evm-messenger/overview.md
View File

@ -7,19 +7,23 @@ Before you get started with this project, make sure you have a local Wormhole Gu
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
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 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, is covered in our breakdown of the EVM code [here](./messenger.md).
The second file, Messenger, is covered in our breakdown of the EVM code at [./messenger.md](./messenger.md).
### Tests
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.
To start, deploy the code, register the applications on each chain and then send a message.
### Orchestrator
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).
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 at [./client.md](./client.md).
### xdapp.config.json
This maintains some constants about the chains RPC endpoints, private keys used to deploy code, etc. It also includes the Wormhole RPC endpoint.

2
src/projects/summary.md
View File

@ -1,2 +1,2 @@
# Projects
The projects for this repository are located [here](https://github.com/certusone/xdapp-book/tree/main/projects).
The projects for this repository are located at [https://github.com/certusone/xdapp-book/tree/main/projects](https://github.com/certusone/xdapp-book/tree/main/projects).

207
src/reference/contracts.md
View File

@ -1,126 +1,129 @@
# Contracts
Here you can find the addresses for the deployed contracts on all the chains that Wormhole supports, including Testnet.
The SDK makes these addresses available in the `CONTRACTS` constant.
Here you can find the addresses for the deployed contracts on all the chains that Wormhole supports, including testnet.
The [constants](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/sdk/js/src/utils/consts.ts) of the Wormhole SDK always has the most up-to-date contract addresses, along with additional useful constants. Check there if something you're looking for isn't found here.
## Mainnet
### Core Bridge
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :-------------------- | :---------------- | :----------- | :------ |
| Solana | 1 | mainnet-beta | worm2ZoG2kUd4vFXhvjh93UUH596ayRfgQ2MgjNMTth |
| Ethereum | 2 | 1 | 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B |
| Terra Classic | 3 | columbus-5 | terra1dq03ugtd40zu9hcgdzrsq6z2z4hwhc9tqk2uy5 |
| Binance Smart Chain | 4 | 56 | 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B |
| Polygon | 5 | 137 | 0x7A4B5a56256163F07b2C80A7cA55aBE66c4ec4d7 |
| Avalanche (C-Chain) | 6 | 43114 | 0x54a8e5f9c4CbA08F9943965859F6c34eAF03E26c |
| Oasis (Emerald) | 7 | 4262 | 0xfE8cD454b4A1CA468B57D79c0cc77Ef5B6f64585 |
| Aurora | 9 | 1313161554 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Fantom | 10 | 250 | 0x126783A6Cb203a3E35344528B26ca3a0489a1485 |
| Karura | 11 | 686 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Acala | 12 | 787 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Klaytn | 13 | 8217 | 0x0C21603c4f3a6387e241c0091A7EA39E43E90bb7 |
| Celo | 14 | 42220 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Terra | 18 | phoenix-1 | terra12mrnzvhx3rpej6843uge2yyfppfyd3u9c3uq223q8sl48huz9juqffcnh |
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :------------------ | :---------------- | :----------- | :-------------------------------------------------------------- |
| Solana | 1 | mainnet-beta | worm2ZoG2kUd4vFXhvjh93UUH596ayRfgQ2MgjNMTth |
| Ethereum | 2 | 1 | 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B |
| Terra Classic | 3 | columbus-5 | terra1dq03ugtd40zu9hcgdzrsq6z2z4hwhc9tqk2uy5 |
| Binance Smart Chain | 4 | 56 | 0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B |
| Polygon | 5 | 137 | 0x7A4B5a56256163F07b2C80A7cA55aBE66c4ec4d7 |
| Avalanche (C-Chain) | 6 | 43114 | 0x54a8e5f9c4CbA08F9943965859F6c34eAF03E26c |
| Oasis (Emerald) | 7 | 4262 | 0xfE8cD454b4A1CA468B57D79c0cc77Ef5B6f64585 |
| Aurora | 9 | 1313161554 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Fantom | 10 | 250 | 0x126783A6Cb203a3E35344528B26ca3a0489a1485 |
| Karura | 11 | 686 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Acala | 12 | 787 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| Klaytn | 13 | 8217 | 0x0C21603c4f3a6387e241c0091A7EA39E43E90bb7 |
| Celo | 14 | 42220 | 0xa321448d90d4e5b0A732867c18eA198e75CAC48E |
| NEAR | 15 | | contract.wormhole_crypto.near |
| Terra | 18 | phoenix-1 | terra12mrnzvhx3rpej6843uge2yyfppfyd3u9c3uq223q8sl48huz9juqffcnh |
### Token Bridge
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :-------------------- | :---------------- | :----------- | :------ |
| Solana | 1 | mainnet-beta | wormDTUJ6AWPNvk59vGQbDvGJmqbDTdgWgAqcLBCgUb |
| Ethereum | 2 | 1 | 0x3ee18B2214AFF97000D974cf647E7C347E8fa585 |
| Terra | 3 | columbus-5 | terra10nmmwe8r3g99a9newtqa7a75xfgs2e8z87r2sf |
| Binance Smart Chain | 4 | 56 | 0xB6F6D86a8f9879A9c87f643768d9efc38c1Da6E7 |
| Polygon | 5 | 137 | 0x5a58505a96D1dbf8dF91cB21B54419FC36e93fdE |
| Avalanche (C-Chain) | 6 | 43114 | 0x0e082F06FF657D94310cB8cE8B0D9a04541d8052 |
| Oasis (Emerald) | 7 | 4262 | 0xfE8cD454b4A1CA468B57D79c0cc77Ef5B6f64585 |
| Aurora | 9 | 1313161554 | 0x51b5123a7b0F9b2bA265f9c4C8de7D78D52f510F |
| Fantom | 10 | 250 | 0x7C9Fc5741288cDFdD83CeB07f3ea7e22618D79D2 |
| Karura | 11 | 686 | 0xae9d7fe007b3327AA64A32824Aaac52C42a6E624 |
| Acala | 12 | 787 | 0xae9d7fe007b3327AA64A32824Aaac52C42a6E624 |
| Klaytn | 13 | 8217 | 0x5b08ac39EAED75c0439FC750d9FE7E1F9dD0193F |
| Celo | 14 | 42220 | 0x796Dff6D74F3E27060B71255Fe517BFb23C93eed |
| Terra | 18 | phoenix-1 | terra153366q50k7t8nn7gec00hg66crnhkdggpgdtaxltaq6xrutkkz3s992fw9 |
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :------------------ | :---------------- | :----------- | :--------------------------------------------------------------- |
| Solana | 1 | mainnet-beta | wormDTUJ6AWPNvk59vGQbDvGJmqbDTdgWgAqcLBCgUb |
| Ethereum | 2 | 1 | 0x3ee18B2214AFF97000D974cf647E7C347E8fa585 |
| Terra | 3 | columbus-5 | terra10nmmwe8r3g99a9newtqa7a75xfgs2e8z87r2sf |
| Binance Smart Chain | 4 | 56 | 0xB6F6D86a8f9879A9c87f643768d9efc38c1Da6E7 |
| Polygon | 5 | 137 | 0x5a58505a96D1dbf8dF91cB21B54419FC36e93fdE |
| Avalanche (C-Chain) | 6 | 43114 | 0x0e082F06FF657D94310cB8cE8B0D9a04541d8052 |
| Oasis (Emerald) | 7 | 4262 | 0xfE8cD454b4A1CA468B57D79c0cc77Ef5B6f64585 |
| Aurora | 9 | 1313161554 | 0x51b5123a7b0F9b2bA265f9c4C8de7D78D52f510F |
| Fantom | 10 | 250 | 0x7C9Fc5741288cDFdD83CeB07f3ea7e22618D79D2 |
| Karura | 11 | 686 | 0xae9d7fe007b3327AA64A32824Aaac52C42a6E624 |
| Acala | 12 | 787 | 0xae9d7fe007b3327AA64A32824Aaac52C42a6E624 |
| Klaytn | 13 | 8217 | 0x5b08ac39EAED75c0439FC750d9FE7E1F9dD0193F |
| Celo | 14 | 42220 | 0x796Dff6D74F3E27060B71255Fe517BFb23C93eed |
| NEAR | 15 | | contract.portalbridge.near |
| Terra | 18 | phoenix-1 | terra153366q50k7t8nn7gec00hg66crnhkdggpgdtaxltaq6xrutkkz3s992fw9 |
### NFT Bridge
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :-------------------- | :---------------- | :----------- | :------ |
| Solana | 1 | mainnet-beta | WnFt12ZrnzZrFZkt2xsNsaNWoQribnuQ5B5FrDbwDhD |
| Ethereum | 2 | 1 | 0x6FFd7EdE62328b3Af38FCD61461Bbfc52F5651fE |
| Binance Smart Chain | 4 | 56 | 0x5a58505a96D1dbf8dF91cB21B54419FC36e93fdE |
| Polygon | 5 | 137 | 0x90BBd86a6Fe93D3bc3ed6335935447E75fAb7fCf |
| Avalanche (C-Chain) | 6 | 43114 | 0xf7B6737Ca9c4e08aE573F75A97B73D7a813f5De5 |
| Oasis (Emerald) | 7 | 4262 | 0x04952D522Ff217f40B5Ef3cbF659EcA7b952a6c1 |
| Aurora | 9 | 1313161554 | 0x6dcC0484472523ed9Cdc017F711Bcbf909789284 |
| Fantom | 10 | 250 | 0xA9c7119aBDa80d4a4E0C06C8F4d8cF5893234535 |
| Karura | 11 | 686 | 0xb91e3638F82A1fACb28690b37e3aAE45d2c33808 |
| Acala | 12 | 787 | 0xb91e3638F82A1fACb28690b37e3aAE45d2c33808 |
| Klaytn | 13 | 8217 | 0x3c3c561757BAa0b78c5C025CdEAa4ee24C1dFfEf |
| Celo | 14 | 42220 | 0xA6A377d75ca5c9052c9a77ED1e865Cc25Bd97bf3 |
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :------------------ | :---------------- | :----------- | :------------------------------------------ |
| Solana | 1 | mainnet-beta | WnFt12ZrnzZrFZkt2xsNsaNWoQribnuQ5B5FrDbwDhD |
| Ethereum | 2 | 1 | 0x6FFd7EdE62328b3Af38FCD61461Bbfc52F5651fE |
| Binance Smart Chain | 4 | 56 | 0x5a58505a96D1dbf8dF91cB21B54419FC36e93fdE |
| Polygon | 5 | 137 | 0x90BBd86a6Fe93D3bc3ed6335935447E75fAb7fCf |
| Avalanche (C-Chain) | 6 | 43114 | 0xf7B6737Ca9c4e08aE573F75A97B73D7a813f5De5 |
| Oasis (Emerald) | 7 | 4262 | 0x04952D522Ff217f40B5Ef3cbF659EcA7b952a6c1 |
| Aurora | 9 | 1313161554 | 0x6dcC0484472523ed9Cdc017F711Bcbf909789284 |
| Fantom | 10 | 250 | 0xA9c7119aBDa80d4a4E0C06C8F4d8cF5893234535 |
| Karura | 11 | 686 | 0xb91e3638F82A1fACb28690b37e3aAE45d2c33808 |
| Acala | 12 | 787 | 0xb91e3638F82A1fACb28690b37e3aAE45d2c33808 |
| Klaytn | 13 | 8217 | 0x3c3c561757BAa0b78c5C025CdEAa4ee24C1dFfEf |
| Celo | 14 | 42220 | 0xA6A377d75ca5c9052c9a77ED1e865Cc25Bd97bf3 |
## Testnet
### Core Bridge
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :--------------------- | :---------------- | :----------- | :------ |
| Solana | 1 | devnet | 3u8hJUVTA4jH1wYAyUur7FFZVQ8H635K3tSHHF4ssjQ5 |
| Ethereum (Goerli) | 2 | 5 | 0x706abc4E45D419950511e474C7B9Ed348A4a716c |
| Ethereum (Ropsten) | 10001 | 3 | 0x210c5F5e2AF958B4defFe715Dc621b7a3BA888c5 |
| Terra | 3 | bombay-12 | terra1pd65m0q9tl3v8znnz5f5ltsfegyzah7g42cx5v |
| Binance Smart Chain | 4 | 97 | 0x68605AD7b15c732a30b1BbC62BE8F2A509D74b4D |
| Polygon (Mumbai) | 5 | 80001 | 0x0CBE91CF822c73C2315FB05100C2F714765d5c20 |
| Avalanche (Fuji) | 6 | 43113 | 0x7bbcE28e64B3F8b84d876Ab298393c38ad7aac4C |
| Oasis (Emerald Testnet)| 7 | 42261 | 0xc1C338397ffA53a2Eb12A7038b4eeb34791F8aCb |
| Algorand (Testnet) | 8 | | 86525623 |
| Aurora | 9 | 1313161555 | 0xBd07292de7b505a4E803CEe286184f7Acf908F5e |
| Fantom | 10 | 4002 | 0x1BB3B4119b7BA9dfad76B0545fb3F531383c3bB7 |
| Karura | 11 | 686 | 0xE4eacc10990ba3308DdCC72d985f2a27D20c7d03 |
| Acala | 12 | 787 | 0x4377B49d559c0a9466477195C6AdC3D433e265c0 |
| Klaytn | 13 | 1001 | 0x1830CC6eE66c84D2F177B94D544967c774E624cA |
| Celo | 14 | 44787 | 0x88505117CA88e7dd2eC6EA1E13f0948db2D50D56 |
| Terra | 18 | pisco-1 | terra19nv3xr5lrmmr7egvrk2kqgw4kcn43xrtd5g0mpgwwvhetusk4k7s66jyv0 |
| Injective | 19 | testnet | inj1xx3aupmgv3ce537c0yce8zzd3sz567syuyedpg |
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :---------------------- | :---------------- | :--------- | :--------------------------------------------------------------- |
| Solana | 1 | devnet | 3u8hJUVTA4jH1wYAyUur7FFZVQ8H635K3tSHHF4ssjQ5 |
| Ethereum (Goerli) | 2 | 5 | 0x706abc4E45D419950511e474C7B9Ed348A4a716c |
| Ethereum (Ropsten) | 10001 | 3 | 0x210c5F5e2AF958B4defFe715Dc621b7a3BA888c5 |
| Terra | 3 | bombay-12 | terra1pd65m0q9tl3v8znnz5f5ltsfegyzah7g42cx5v |
| Binance Smart Chain | 4 | 97 | 0x68605AD7b15c732a30b1BbC62BE8F2A509D74b4D |
| Polygon (Mumbai) | 5 | 80001 | 0x0CBE91CF822c73C2315FB05100C2F714765d5c20 |
| Avalanche (Fuji) | 6 | 43113 | 0x7bbcE28e64B3F8b84d876Ab298393c38ad7aac4C |
| Oasis (Emerald Testnet) | 7 | 42261 | 0xc1C338397ffA53a2Eb12A7038b4eeb34791F8aCb |
| Algorand (Testnet) | 8 | | 86525623 |
| Aurora | 9 | 1313161555 | 0xBd07292de7b505a4E803CEe286184f7Acf908F5e |
| Fantom | 10 | 4002 | 0x1BB3B4119b7BA9dfad76B0545fb3F531383c3bB7 |
| Karura | 11 | 686 | 0xE4eacc10990ba3308DdCC72d985f2a27D20c7d03 |
| Acala | 12 | 787 | 0x4377B49d559c0a9466477195C6AdC3D433e265c0 |
| Klaytn | 13 | 1001 | 0x1830CC6eE66c84D2F177B94D544967c774E624cA |
| Celo | 14 | 44787 | 0x88505117CA88e7dd2eC6EA1E13f0948db2D50D56 |
| NEAR | 15 | | wormhole.wormhole.testnet |
| Terra | 18 | pisco-1 | terra19nv3xr5lrmmr7egvrk2kqgw4kcn43xrtd5g0mpgwwvhetusk4k7s66jyv0 |
| Injective | 19 | testnet | inj1xx3aupmgv3ce537c0yce8zzd3sz567syuyedpg |
### Token Bridge
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :--------------------- | :---------------- | :----------- | :------ |
| Solana | 1 | devnet | DZnkkTmCiFWfYTfT41X3Rd1kDgozqzxWaHqsw6W4x2oe |
| Ethereum (Goerli) | 2 | 5 | 0xF890982f9310df57d00f659cf4fd87e65adEd8d7 |
| Ethereum (Ropsten) | 10001 | 3 | 0xF174F9A837536C449321df1Ca093Bb96948D5386 |
| Terra | 3 | bombay-12 | terra1pseddrv0yfsn76u4zxrjmtf45kdlmalswdv39a |
| Binance Smart Chain | 4 | 97 | 0x9dcF9D205C9De35334D646BeE44b2D2859712A09 |
| Polygon (Mumbai) | 5 | 80001 | 0x377D55a7928c046E18eEbb61977e714d2a76472a |
| Avalanche (Fuji) | 6 | 43113 | 0x61E44E506Ca5659E6c0bba9b678586fA2d729756 |
| Oasis (Emerald Testnet)| 7 | 42261 | 0x88d8004A9BdbfD9D28090A02010C19897a29605c |
| Algorand (Testnet) | 8 | | 86525641 |
| Aurora | 9 | 1313161555 | 0xD05eD3ad637b890D68a854d607eEAF11aF456fba |
| Fantom | 10 | 4002 | 0x599CEa2204B4FaECd584Ab1F2b6aCA137a0afbE8 |
| Karura | 11 | 686 | 0xd11De1f930eA1F7Dd0290Fe3a2e35b9C91AEFb37 |
| Acala | 12 | 787 | 0xebA00cbe08992EdD08ed7793E07ad6063c807004 |
| Klaytn | 13 | 1001 | 0xC7A13BE098720840dEa132D860fDfa030884b09A |
| Celo | 14 | 44787 | 0x05ca6037eC51F8b712eD2E6Fa72219FEaE74E153 |
| Injective | 19 | testnet | inj1q0e70vhrv063eah90mu97sazhywmeegp7myvnh |
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :---------------------- | :---------------- | :--------- | :------------------------------------------- |
| Solana | 1 | devnet | DZnkkTmCiFWfYTfT41X3Rd1kDgozqzxWaHqsw6W4x2oe |
| Ethereum (Goerli) | 2 | 5 | 0xF890982f9310df57d00f659cf4fd87e65adEd8d7 |
| Ethereum (Ropsten) | 10001 | 3 | 0xF174F9A837536C449321df1Ca093Bb96948D5386 |
| Terra | 3 | bombay-12 | terra1pseddrv0yfsn76u4zxrjmtf45kdlmalswdv39a |
| Binance Smart Chain | 4 | 97 | 0x9dcF9D205C9De35334D646BeE44b2D2859712A09 |
| Polygon (Mumbai) | 5 | 80001 | 0x377D55a7928c046E18eEbb61977e714d2a76472a |
| Avalanche (Fuji) | 6 | 43113 | 0x61E44E506Ca5659E6c0bba9b678586fA2d729756 |
| Oasis (Emerald Testnet) | 7 | 42261 | 0x88d8004A9BdbfD9D28090A02010C19897a29605c |
| Algorand (Testnet) | 8 | | 86525641 |
| Aurora | 9 | 1313161555 | 0xD05eD3ad637b890D68a854d607eEAF11aF456fba |
| Fantom | 10 | 4002 | 0x599CEa2204B4FaECd584Ab1F2b6aCA137a0afbE8 |
| Karura | 11 | 686 | 0xd11De1f930eA1F7Dd0290Fe3a2e35b9C91AEFb37 |
| Acala | 12 | 787 | 0xebA00cbe08992EdD08ed7793E07ad6063c807004 |
| Klaytn | 13 | 1001 | 0xC7A13BE098720840dEa132D860fDfa030884b09A |
| Celo | 14 | 44787 | 0x05ca6037eC51F8b712eD2E6Fa72219FEaE74E153 |
| Celo | 15 | | token.wormhole.testnet |
| Injective | 19 | testnet | inj1q0e70vhrv063eah90mu97sazhywmeegp7myvnh |
### NFT Bridge
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :--------------------- | :---------------- | :----------- | :------ |
| Solana | 1 | devnet | 2rHhojZ7hpu1zA91nvZmT8TqWWvMcKmmNBCr2mKTtMq4 |
| Ethereum (Goerli) | 2 | 5 | 0xD8E4C2DbDd2e2bd8F1336EA691dBFF6952B1a6eB |
| Ethereum (Ropsten) | 10001 | 3 | 0x2b048Da40f69c8dc386a56705915f8E966fe1eba |
| Binance Smart Chain | 4 | 97 | 0xcD16E5613EF35599dc82B24Cb45B5A93D779f1EE |
| Polygon (Mumbai) | 5 | 80001 | 0x51a02d0dcb5e52F5b92bdAA38FA013C91c7309A9 |
| Avalanche (Fuji) | 6 | 43113 | 0xD601BAf2EEE3C028344471684F6b27E789D9075D |
| Oasis (Emerald Testnet)| 7 | 42261 | 0xC5c25B41AB0b797571620F5204Afa116A44c0ebA |
| Aurora | 9 | 1313161555 | 0x8F399607E9BA2405D87F5f3e1B78D950b44b2e24 |
| Fantom | 10 | 4002 | 0x63eD9318628D26BdCB15df58B53BB27231D1B227 |
| Karura | 11 | 686 | 0x0A693c2D594292B6Eb89Cb50EFe4B0b63Dd2760D |
| Acala | 12 | 787 | 0x96f1335e0AcAB3cfd9899B30b2374e25a2148a6E |
| Klaytn | 13 | 1001 | 0x94c994fC51c13101062958b567e743f1a04432dE |
| Celo | 14 | 44787 | 0xaCD8190F647a31E56A656748bC30F69259f245Db |
| Chain Name | Wormhole Chain ID | Network ID | Address |
| :---------------------- | :---------------- | :--------- | :------------------------------------------- |
| Solana | 1 | devnet | 2rHhojZ7hpu1zA91nvZmT8TqWWvMcKmmNBCr2mKTtMq4 |
| Ethereum (Goerli) | 2 | 5 | 0xD8E4C2DbDd2e2bd8F1336EA691dBFF6952B1a6eB |
| Ethereum (Ropsten) | 10001 | 3 | 0x2b048Da40f69c8dc386a56705915f8E966fe1eba |
| Binance Smart Chain | 4 | 97 | 0xcD16E5613EF35599dc82B24Cb45B5A93D779f1EE |
| Polygon (Mumbai) | 5 | 80001 | 0x51a02d0dcb5e52F5b92bdAA38FA013C91c7309A9 |
| Avalanche (Fuji) | 6 | 43113 | 0xD601BAf2EEE3C028344471684F6b27E789D9075D |
| Oasis (Emerald Testnet) | 7 | 42261 | 0xC5c25B41AB0b797571620F5204Afa116A44c0ebA |
| Aurora | 9 | 1313161555 | 0x8F399607E9BA2405D87F5f3e1B78D950b44b2e24 |
| Fantom | 10 | 4002 | 0x63eD9318628D26BdCB15df58B53BB27231D1B227 |
| Karura | 11 | 686 | 0x0A693c2D594292B6Eb89Cb50EFe4B0b63Dd2760D |
| Acala | 12 | 787 | 0x96f1335e0AcAB3cfd9899B30b2374e25a2148a6E |
| Klaytn | 13 | 1001 | 0x94c994fC51c13101062958b567e743f1a04432dE |
| Celo | 14 | 44787 | 0xaCD8190F647a31E56A656748bC30F69259f245Db |

4
src/reference/github.md
View File

@ -1,8 +1,8 @@
# Repository
The Wormhole core repository can be found [here](https://github.com/certusone/wormhole).
The Wormhole core repository can be found at [https://github.com/certusone/wormhole](https://github.com/certusone/wormhole).
# Design Documents
Wormhole's component design specifications can be found [here](https://github.com/certusone/wormhole/tree/dev.v2/whitepapers). These outline the reasoning behind design decisions with added technical depth.
Wormhole's component design specifications can be found at [https://github.com/certusone/wormhole/tree/dev.v2/whitepapers](https://github.com/certusone/wormhole/tree/dev.v2/whitepapers). These outline the reasoning behind design decisions with added technical depth.

22
src/reference/glossary.md Normal file
View File

@ -0,0 +1,22 @@
# Glossary
In some instances, Wormhole uses general terms fo decentralized, cross-chain elements as branded verbiage. In most casese, the definition of the general term does not differ from Wormhole's definition though Wormhole's definitions may be more narrow than general interpretations.
**xChain** - Term that referrs to the full range of cross-blockchain interoperability.
[**xData**](../dapps/3_xdataxassets.md) - Data that exists in a layer outside of Layer 1 blockchains, which is accessible by all chains.
[**xAssets**](../dapps/3_xdataxassets.md) - Chain-and-path agnostic token that exists on a layer outside the blockchain ecosystem, which can be used to conduct transactions on any blockchain. There are currently two implemented modules: (1) [Token Bridge Module](../technical/evm/xassetLayer.md) and (2) [NFT Bridge Module](../technical/evm/nftLayer.md)
[**xDapp**](../dapps/4_whatIsanXdapp.md) - Decentralized application that enables users to create and/or use xData.
[**Guardian Network**](../wormhole/5_guardianNetwork.md) - Validators that exist in their own p2p network that serve as Wormhole's oracle by observing activity on-chain and generating signed messages attesting to that activity.
[**Relayer**](../wormhole/6_relayers.md) - Any process which delivers VAAs to a destination.
**Guardian** - One of the 19 validators in the Guardian Network that Contributes to the VAA multisig.
[**VAA**](../wormhole/4_vaa.md) - 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.
[**Wormchain**](../wormhole/8_wormchain.md) - A purpose-built cosmos blockchain which aids the Guardian Network and allows for formal interaction with the Guardians.

22
src/reference/tools.md
View File

@ -1,17 +1,17 @@
# Tools
There are various tools in the Wormhole ecosystem that can help you in developing xDapps. Here are a few of the most notable:
There are a variety of tools in the Wormhole ecosystem that can help you develop xDapps. Here are a few of the most notable:
# Testnet
Wormhole has deployed Core Bridge, Token Bridge and NFT Bridge contracts on various testnets of the chains connected by Wormhole. You can see the deployed addresses [here](./contracts.md). There's only a single Guardian that oversees the testnets, so you might get a higher rate of missed VAAs than you would on mainnet.
### Testnet
Wormhole has deployed Core Bridge, Token Bridge and NFT Bridge contracts on various testnets of the chains connected by Wormhole. You can see the deployed addresses at [./contracts.md](./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).
### 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 at [https://wormholenetwork.com/en/explorer](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, hosted [here](https://certusone.github.io/wormhole).
### 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, hosted at [https://certusone.github.io/wormhole](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 set it up and test against it, start [here](../development/tilt/overview.md).
### Tilt
Tilt is a Kubernetes-based tool that runs a copy of every chain along side a Guardian node to create a simulated testing environment. To set it up and test against it, start at [../development/tilt/overview.md](../development/tilt/overview.md).
# 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).
### 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 at [https://www.npmjs.com/package/@certusone/wormhole-sdk](https://www.npmjs.com/package/@certusone/wormhole-sdk).

19
src/technical/env/environments.md vendored Normal file
View File

@ -0,0 +1,19 @@
# Environment Setup
The bare minimum Wormhole environment is just a blockchain linked up to a Guardian node. There are quite a few ways of accomplishing this, and if you're just looking to get your feet wet, you should try whichever sounds easiest.
However, as you get deeper into cross-chain development, you'll likely find yourself with a growing number of components, dependencies, and teammates in the picture making your development environment more complex. Here are some of the considerations you should have in mind when choosing a development environment which will be well suited for your xDapp.
### What components do I need now? What components will I need in the future?
- You may be able to get a lot done with just an EVM chain and a Guardian. However, as your application gets more sophisticated, components like relayers, frontends, automated tests, databases, explorers, and other blockchains are likely to get added in to the environment.
### What are my dependencies?
- If your smart contracts have no dependencies, it may be possible for you to develop in a vacuum.
- If your smart contracts does have dependencies, there are several options that range from deploying your dependencies in Tilt or use something like [Foundry](https://github.com/foundry-rs/foundry) to simulate an existing testnet or mainnet in your local devnet to working to working directly in testnet alongside other teams.
### How am I going to collaborate?
- You should consider how your teammates or collaborators are going to work in this environment from the start. There are some basic considerations like "how will they access it", but also some subtler points such as ensuring that contracts will deploy deterministically and that automated tests can be trusted to run reliably. The two paths to accomplish this are to use a public environment (testnet), or to ensure the local environment is well controlled (like tilt).

1
src/technical/env/overview.md vendored Normal file
View File

@ -0,0 +1 @@
# Introduction

22
src/technical/env/testnet.md vendored Normal file
View File

@ -0,0 +1,22 @@
# Testnet
Wormhole testnet is spread across many of the most popular testnet blockchains.
The primary reason to use Wormhole testnet is to simplify the management of your dependent contracts. This will vary from blockchain to blockchain.
For example, some blockchain ecosystems have the standard that their contracts are closed-source, and there are no tools to fork mainnet. Other ecosystems, such as EVM, have tools like [foundry](https://github.com/foundry-rs/foundry), which allow you to hardfork the mainnet ecosystem into a local development node.
In short, testnet tends to be the correct choice only when you have contract dependencies, and those dependencies are difficult to get working in a local environment. In most other cases, testnet tends to be more work than it's worth.
If you elect to use testnet, the Wormhole contracts addresses can be found in the [Reference](../../reference/contracts.md) section.
Pros:
- Many other projects deploy their contracts to testnet.
- In ecosystems without extensive local tooling, this may be the preferred development environment.
Cons:
- Many testnets are somewhat unstable and have outages or partitioning events.
- Wormhole Testnet sometimes misses VAAs due to testnet instabilities.
- Testnet tokens are often difficult to acquire.

74
src/technical/env/tilt.md vendored Normal file
View File

@ -0,0 +1,74 @@
# Tilt (Devnet)
### What is Tilt?
[Tilt](https://tilt.dev/) is part of the official Docker ecosystem. It's a tool which allows developers to easily configure a Kubernetes environment for development.
However, in the context of Wormhole, 'Tilt' usually refers to the development environment used by the [Wormhole Core Repository](https://github.com/wormhole-foundation/wormhole). This environment uses Tilt to stand up docker images for all the tools necessary to build across multiple blockchains, including:
- All the Wormhole supported blockchains / ecosystems
- A Guardian Node
- Relayers
- Databases, Redis
- Utility frontends
The 'Tilt' environment (also referred to as Wormhole 'Devnet') is meant to provide an entire cross-chain development stack right out of the box.
### Is Tilt Right for You?
Tilt is generally a good starting point for most developers. Here's a succinct list of the pros and cons of the environment, so you can decide if it's the right fit for you.
### Pros
- Out-of-the-box support for the many components needed to develop across the heterogenous blockchain space.
- Consistent development environment, where contracts deploy deterministically and everything is already linked up.
- Ability to easily enable/disable components as needed.
- Regularly updated as new components join the Wormhole ecosystem.
### Cons
- Relatively high system requirements. This can be mitigated by disabling components.
- Most blockchains are 'fresh' and have no contracts by default. Thus, you may have to deploy your own dependencies, or alter the default tilt configuration.
- Spin-up and rebuild times can be slow. This can result in a slow workflow if you rely on docker rebuilds.
# Setting up Tilt
Tilt functions best in a UNIX-style environment. For Windows users, using a WSL environment is recommended.
In order to run the Tilt environment, you'll first need to make sure you have [Tilt](https://docs.tilt.dev/install.html) and [Go](https://go.dev/doc/install) installed.
Once you've installed these two dependencies, just clone the Wormhole Core Repository and start Tilt.
```
git clone --branch dev.v2 https://github.com/wormhole-foundation/wormhole.git
cd wormhole
tilt up
```
Be sure to check out the [**Tiltfile**](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/Tiltfile), which has much of the configuration and arguments for the development environment. It's relatively straightforward to enable and disable components. For example, you can disable blockchains by setting them to false at startup
```
tilt up -- --algorand=false --near=false --solana=false terra_classic=false terra2=false
```
# Using Tilt
Tilt can pretty much be treated as though it's an external environment that you can easily spin up and tear down.
If you've followed the standard setup, all your resources will be bound to various ports on localhost. To see all the endpoints which are being hosted in your Tilt environment, you should check the Tilt dashboard, located at [http://localhost:10350/overview](http://localhost:10350/overview).
Tilt is alos referred to as 'Devnet' in the Wormhole ecosystem, so anywhere you see information labeled as 'Devnet', you can apply it to Tilt.
For example, you can find all the deployed contract addresses in the 'Devnet' [constants](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/sdk/js/src/utils/consts.ts) of the Wormhole Typescript SDK.
Useful information pertaining to funded wallets & useful private keys can also be found in the [devnet.md](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/docs/devnet.md) file of the docs.
From here, Tilt is quite similar to using Testnet, and you should look at the [Tooling](./tooling.md) page for additional resources.
In order to shut down Tilt, simply run
```
tilt down
```

60
src/technical/env/tooling.md vendored Normal file
View File

@ -0,0 +1,60 @@
# Tooling
Regardless of the development environment that you use, there are a few wormhole-specific tools you should know about.
### [Wormhole Core Repository](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/)
- Most developers find it useful to clone the Wormhole Core repository. This repository provides the Devnet Tilt environment, plenty of useful code examples and tests, along with some utilities which do not have an official release package.
### [Worm CLI tool](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/clients/js)
- Swiss-Army Knife Utility CLI tool. Excellent for creating one-off VAAs, parsing VAAs, reading Wormhole contract configurations, and more.
### [Orchestrator](https://github.com/wormhole-foundation/xdapp-book/blob/main/projects/evm-messenger/orchestrator.js)
- Small WIP tool which comes as part of the [Wormhole Local Validator](./wlv.md) environment. Used to quickly deploy and redeploy multiple smart contracts. Will eventually become part of a larger deployment management tool.
### [Wormhole SDKs](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/sdk)
- Libraries in various languages to help with interacting with Wormhole contracts.
### [Wormhole Typescript SDK](https://www.npmjs.com/package/@certusone/wormhole-sdk)
- Typescript SDK destributed on npm. Can greatly aid in writing frontend code for xDapps and utilizing the Wormhole Token Bridge directly.
### [Wormhole Spy SDK](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/spydk/js)
- The Wormhole Spy SDK allows you to listen to all of the activity on the Guardian Network.
### [Reference Bridge UI](https://github.com/wormhole-foundation/example-token-bridge-ui)
- An example GUI which can be used to perform token transfers around the ecosystem.
### [Explorer](https://wormhole.com/explorer/)
- Resource for looking at individual transfers statuses on mainnet and testnet.
<!--
how to use on tilt?
-->
<!--
Example projects
-->
## Example Projects
### [Basic Examples](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects)
- Several example projects are bundled here. They show minimum-code examples for how to send messages, tokens, and other common functions.
### [ICCO](https://github.com/certusone/wormhole-icco)
- Productionized, audited xDapp which does cross-chain token launches. Great example of what a robust xDapp, written across multiple ecosystems looks like.
### [Native Swap](https://github.com/certusone/wormhole-nativeswap-example)
- Example cross-chain dex, utilizing the stablecoin highway model.
### [Wormhole Examples](https://github.com/certusone/wormhole-examples)
- More example components. Has a mix of relayers, xDapps, NFT projects, and more.

120
src/technical/env/troubleshooting.md vendored Normal file
View File

@ -0,0 +1,120 @@
# Troubleshooting
Tilt, Kubernetes, and Docker may be new tools for developers entering the Wormhole ecosystem. This section is meant to provide some additional support when setting up the Wormhole Tilt environment.
# macOS Install
## Prerequisites
Having `homebrew` on your system makes the installation really straightforward. You can grab it with:
```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
From there, all the other installs are one-liners.
### 1. Install Go
```sh
brew install go
```
### 2. Install Docker
```sh
brew install docker
```
After installation, go into Docker settings and switch ON `kubernetes`. Also configure Docker to have 4 CPUs and ~16GB of RAM.
### 3. Install Tilt
```sh
brew install tilt
```
### 4. Clone Wormhole Repo and Start Tilt
```sh
git clone --branch dev.v2 https://github.com/wormhole-foundation/wormhole.git
```
```sh
cd wormhole/
tilt up
```
You'll be able to access the Tilt UI at
`localhost:10350`
# Linux & WSL Install
## Script Setup
If you're using a Debian distro, you should run the [dev-setup.sh](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/scripts/dev-setup.sh) script. Even if you're not using Debian, this script still contains the main steps for setup.
## Regular Setup
### 1. Install Go
```sh
wget https://go.dev/dl/go1.18.1.linux-amd64.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.18.1.linux-amd64.tar.gz
```
### 2. Install Docker
If you're using Linux with a window manager, consider getting Docker Desktop instead of the following command. It comes with Kubernetes built in and you won't need to download `minikube`. It's recommended to have at least 4 CPUs and 16GB RAM dedicated to Docker.
Also, make absolutely sure that you set up Docker as a non-root user.
[https://docs.docker.com/engine/install/ubuntu/#installation-methods](https://docs.docker.com/engine/install/ubuntu/#installation-methods)
### 3a. (Docker Desktop Install)
Enable Kubernetes by going into Settings > Kubernetes
### 3b. (Non Docker Desktop)
Install [`minikube`](https://minikube.sigs.k8s.io/docs/start/).
Configure minikube:
```
minikube start --driver=docker --kubernetes-version=v1.23.3 --cpus=4 --memory=14G --disk-size=10G --namespace=wormhole
```
Minikube needs to be running for tilt to work, so always make sure to run `minikube start` before you bring up tilt.
### 4. Install Tilt
Install Tilt by copy pasting this into the Terminal:
```sh
curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash
```
### 5. Clone the Wormhole Repo and start Tilt
```sh
git clone --branch dev.v2 https://github.com/wormhole-foundation/wormhole.git
```
If you're running Tilt on your machine:
```sh
cd wormhole/
tilt up
```
If you're running Tilt in a VM, you'll need to pass in some extra flags to enable Tilt to listen to incoming traffic from external addresses:
```sh
cd wormhole
tilt up --host=0.0.0.0 -- --webHost=0.0.0.0
```
You can now access the Tilt UI at either `localhost:10350` or `vm_external_ip:10350`.
If the VM's external IP doesn't work, check firewall and port settings to make sure your VM allows incoming traffic.

33
src/technical/env/wlv.md vendored Normal file
View File

@ -0,0 +1,33 @@
# Wormhole Local Validator
## What is Wormhole Local Validator (WLV)?
[Wormhole Local Validator](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects/wormhole-local-validator) is meant to be the simplest custom environment. It consists only of a dockerized Guardian image, and some utility tooling to aid with contract management. This allows you to set it up with any blockchain you'd like.
## Is WLV Right for You?
Here's a succinct list of the pros and cons of the environment, so you can decide if it's the right fit for you.
### Pros
- Lightweight, low system resource demand.
- Fast iteration times.
- Can be added into an existing blockchain development setup.
### Cons
- You may end up reinventing the tilt/testnet environment as you add more components.
## Setting up Wormhole Local Validator
You will need Docker running in order to set up WLV. If you're on desktop, [Docker Desktop](https://docs.docker.com/get-docker/) is generally the best choice, though [Docker Engine](https://docs.docker.com/engine/) works fine too.
From there, you just need nodes for the blockchains you're interested in developing on. There is code to spin up EVM and Solana local validators included in the WLV project repo, as well as scripts to deploy the necessary Wormhole contracts to your local instances.
Further information can be found in the project's [README](https://github.com/wormhole-foundation/xdapp-book/blob/main/projects/wormhole-local-validator/README.md).
## Troubleshooting
Q: Anvil isn't working
- While Foundry's 'forge' tool is the generally recommended tool for EVM contract compilation, anvil isn't currently compatible with guardiand. Anvil reports block headers in a way which is non-compliant with go-ethereum, which means the guardian node can't correctly read anvil headers.

136
src/technical/evm/bestPractices.md Normal file
View File

@ -0,0 +1,136 @@
# Best Practices
The Wormhole contracts were designed in a manner such that composability is the default, but maximizing composability requires that xDapp developers follow certain conventions around the sending and receiving of messages.
# Sending Messages
When sending messages, you should follow the same paradigm as is used by the Wormhole modules, namely
- Don't couple the message emission to the message delivery
- Pass through all the optional arguments (like nonce)
- Always return the sequence
### Good Example
```solidity
// This function defines a super simple Wormhole 'module'.
// A module is just a piece of code which knows how to emit a composable message
// which can be utilized by other contracts.
function emitMyMessage(address intendedRecipient, uint32 nonce)
public returns (uint64 sequence) {
// Nonce is passed though to the core bridge.
// This allows other contracts to utilize it for batching or processing.
// intendedRecipient is key for composability!
// This field will allow the destination contract to enforce
// that the correct contract is submitting this VAA.
// 1 is the consistency level,
// this message will be emitted after only 1 confirmation
sequence = core_bridge.publishMessage(nonce, "My Message to " + intendedRecipient, 1);
// The sequence is passed back to the caller, which can be useful relay information.
// Relaying is not done here, because it would 'lock' others into the same relay mechanism.
}
// This portion of the code which deals with composition and delivery.
// Its job is to string together multiple modules, and ensure they get relayed
// This code can be private or public, because it's tightly coupled to application.
// Do whatever you need to here.
function sendMyMessage() private {
// First, emit a message intended for MY_OTHER_CONTRACT with nonce zero.
// Because processMyMessage enforces that msg.sender must equal the intendedRecipient,
// no one but MY_OTHER_CONTRACT will be able to call processMyMessage
// with the message emitted from this transaction.
// However, another contract could call emitMyMessage in a different transaction
// using their own address as the recipient.
// This allows for composability of the module logic while still being secure!
emitMyMessage(MY_OTHER_CONTRACT, 0);
// Suppose I also want to send tokens to my contract on the OTHER_CHAIN
// Because transferTokensWithPayload is a composable message, I can include it.
// Because the nonce of both these messages is 0, they will be combined into a batch VAA.
// NOTE: transferTokens (the basic transfer) is NOT considered a composable message
token_bridge.transferTokensWithPayload(SOME_TOKEN, SOME_AMOUNT, OTHER_CHAIN, MY_OTHER_CONTRACT,
0, null);
// Lastly, I request that the batch for nonce 0 be delivered to MY_OTHER_CONTRACT
relayer_contract.requestDelivery(OTHER_CHAIN, MY_OTHER_CONTRACT, 0, getRelayerFeeAmount());
}
```
# Receiving Messages
The best practices for receiving messages employ similar concepts. You should keep in mind that other contracts might want to integrate with your specific logic. As such, you shouldn't tie your verification logic to the delivery mechanism of your VAAs, and you should also give external integrators a safe way to compose with your module.
### **_Critical!_**
- Always verify that the emitterAddress of the VAA comes from a contract you trust.
- If the message should not be allowed to be 'replayed', immediately mark its hash as processed.
- If your VAAs aren't replayable, you almost always want to include and enforce an intended recipient. Otherwise anyone can call your verify function directly with the single VAA, which will make life much harder for you and your integrators who want to process multiple VAAs at once. This is referred to as a 'scoop' exploit.
### Composability
- When processing a VAA, always treat the messages as single VAAs. Destructuring batch VAAs is the responsibility of the integrator.
- Once you have the function written to verify your message, pretend you are an external integrator.
### Good Example
```
// Verification accepts a single VAA, and is publicly callable.
function processMyMessage(bytes32 memory VAA) public {
// This call accepts single VAAs and headless VAAs
(IWormhole.VM memory vm, bool valid, string memory reason) =
core_bridge.parseAndVerifyVM(VAA);
// Ensure core contract verification succeeded.
require(valid, reason);
// Ensure the emitterAddress of this VAA is a trusted address
require(myTrustedContracts[vm.emitterChainId] ==
vm.emitterAddress, "Invalid Emitter Address!");
// Check that the VAA hasn't already been processed (replay protection)
require(!processedMessages[vm.hash], "Message already processed");
// Check that the contract which is processing this VAA is the intendedRecipient
// If the two aren't equal, this VAA may have bypassed its intended entrypoint.
// This exploit is referred to as 'scooping'.
require(parseIntendedRecipient(vm.payload) == msg.sender);
// Add the VAA to processed messages so it can't be replayed
processedMessages[vm.hash] = true
// The message content can now be trusted.
doBusinessLogic(vm.payload)
}
//This is the function which would receive the the VAA from the relayer
function receiveVAA(bytes32 memory batchVAA) public {
// First, call the core bridge to verify the batchVAA
// All the individual VAAs inside the batchVAA will be cached,
// and you will receive headless VAAs inside the VM2 object.
// Headless VAAs are verifiable by parseAndVerifyVM.
(IWormhole.VM2 memory vm2, bool valid, string memory reason) =
core_bridge.parseAndVerifyBatchVM(batchVAA, true)
// I know from sendMyMessage that the first VAA is a token bridge VAA,
// so let's hand that off to the token bridge module.
bytes vaaData = token_bridge.completeTransferWithPayload(vm2.payloads[0])
// The second VAA is my message, let's hand that off to my module.
processMyMessage(vm2.payloads[1])
}
```
<!--
TODO these are not actually functioning examples and some of the interactions are incorrect. Demonstrates the concept.
>

98
src/technical/evm/coreLayer.md Normal file
View File

@ -0,0 +1,98 @@
# Core Message Layer
This section will explain how to properly interact with the Wormhome Core Message Layer in an EVM ecosystem.
Messages in Wormhole take the form of a Verified Action Approval (VAA) and both terms can be used interchangably. The rest of this section will only use the term VAA.
## Configuring the Interface
[Here](https://github.com/wormhole-foundation/wormhole/blob/dev.v2/ethereum/contracts/interfaces/IWormhole.sol) is the interface for applications to interact with Wormhole's Core Contract to publish VAAs or verify and parse a received VAAs.
Instantiating the interface will depend on the contract address of your development ecosystem and blockchain.
Below is an example line of code to instantiate the interface for mainnet Ethereum:
```
address private wormhole_core_bridge_address = address(0x98f3c9e6E3fAce36bAAd05FE09d375Ef1464288B);
IWormhole core_bridge = IWormhole(wormhole_core_bridge_address);
```
## Primary functions
The Wormhole Core Layer effectively only has two important interactions -- (1) emit VAAs, and (2) parse and verify VAAs that originated from other chains.
### Emitting a VAA
There are two forms that VAAs can be emitted within Wormhole:
- Single VAA: all messages will be emitted in this format
- Batch VAA: messages that are generated from the same transaction will be emitted in this format. This feature was developed to provide an easier paradigm for composability and better gas efficiency for more involved cross-chain activity.
To emit a VAA, always use `publishMessage` which takes in the following arguments:
1. `nonce` (uint32): a number assigned to each message
- The `nonce` provides a mechanism by which to group messages together within a Batch VAA.
- How Batch VAAs are generated based on a message's `nonce` is described below.
2. `Consistency` (uint8): the number of blocks that Guardians will wait before signing a message
- Each blockchain has different finality periods. In general, higher consistencies mean more security against blockchain reorgs.
- [Here]() are the consistency levels by blockchain that are used by the xAsset layer to have a high level of guarantee against reorgs.
3. `Payload` (bytes[]): raw bytes to emit
- It is up to the emitting contract to properly define this arbitrary set of bytes.
`publishMessage` will output a `sequence` (uint64) that is used in conjunction with `emitterChainID` and `emitterAddress` to retrive the generated VAA from the Guardian Network.
> How Batch VAAs are generated
>
> There are two mechanisms that allow messages to be Batched together that represent a base and more advanced level of compsability.
>
> 1. All messages originating from the same transaction will be batched together.
> 2. Messages that originate from the same transaction and are assigned the same nonce are additionally batched together.
>
> _Note: Single VAAs will always be emitted for each message within a transaction, regardless of if a message is included in a batch or not._
>
> Here is an example of how messages generated from the same transaction may be batched together:
>
> A transaction X that generates 6 messages [A, B, C, D, E, F] that are assigned `nonce` [1, 2, 2, 3, 3, 4] respectively will generate the following VAAs:
> - (1) full transaction batch VAA
> - [A, B, C, D, E, F]
> - (2) smaller batch VAA
> - [B, C]
> - [D, E]
> - (6) single VAA
> - [A]
> - [B]
> - [C]
> - [D]
> - [E]
> - [F]
### Parsing and Verifying a VAA
Parsing and Verifying a VAA will depend on the type of VAA that your application expects: a Single VAA or a Batch VAA.
For either VAA type, remember to collect gas fees associated with submitting them on-chain after all VAAs have been verified.
**Single VAA**
To properly parse and verify a single VAA, always use `parseAndVerifyVM` which takes in one argument: `encodedVM` (bytes). This function will return three arguments:
1. `vm` (VM): Structured data that reflects the content of the VAA.
- A breakdown of this message format is described in the [VAA](../../wormhole/4_vaa.md) section. Aside from the header information, which can be considered 'trusted', it is up to the recipient contract to properly parse the remaining payload, as this contains the verbatim message sent from the emitting contract.
2. `valid` (bool): Boolean that reflects whether or not the VAA was properly signed by the Guardian Network
3. `reason` (string): Explanatory error message if a VAA is invalid, or an empty string if it is valid.
<!--
TODO
everything about this
**Batch VAA**
To properly parse and verify a batch VAA, always use `parseAndVerifyBatchVM` which takes in two arguments: `encodedVM` (bytes) and `cache` (bool).
Batch VAAs are designed so that relayers can choose to submit any subset of the observations batched together. It is the receiving contract's responsiblity to verify that all VAAs contained in a batch are submitted.
---
Code recommendation, write the code which expects to receive a VAA to utilize parseAndVerifyVM(? unsure if this is the correct call). That way, your code will be able to handle either type 1 VAAs (single VAAs), or type 3 VAAs (headless VAAs). This allows it to utilize both single & batch VAAs and dramatically increases composability. \*this only requires like two or three lines of code, so this would be a good candidate for a code example which shows how to properly use batch vaas without breaking composability. Should note that the module code still ALWAYS needs to verify, but should do so with the 'single' message verifying and then expose that function publicly in order to enable composability.
-->

63
src/technical/evm/nftLayer.md Normal file
View File

@ -0,0 +1,63 @@
# NFT Bridge
This section will explain how to properly interact with the NFT Bridge Module in an EVM ecosystem.
## Configuring the interface
[Here](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/ethereum/contracts/interfaces) is the interface for applications to interact with Wormhole's NFT Bridge.
<!---
TODO
merge down the interface PR and link to actual file
-->
Instantiating the interface will depend on the contract address of your development ecosystem and blockchain.
Below is an example line of code to instantiate the interface for mainnet Ethereum:
```
address private wormhole_NFT_bridge_address = address(0x6FFd7EdE62328b3Af38FCD61461Bbfc52F5651fE);
INFTBridge NFT_bridge = INFTBridge(wormhole_nft_bridge_address);
```
## Transferring a NFT
The Wormhole NFT Bridge only supports tokens compliant with the ERC-721 interface, and functions by creating a 'wrapped NFT' with identical metadata. How this is implemented varies by ecosystem.
**Note**: Unlike xAssets, there is no attestation required for bridging NFTs.
To transfer a NFT, there are three steps:
1. Initiate the NFT transfer
- This function call will return a `sequence` (uint64) that is used in the VAA retrieval step
```
transferNFT(tokenAddress, tokenID, recipientChain, recipient, nonce);
```
2. Retrieve the emitted VAA from the Guardian Network. (Usually done by a relayer)
- _Note: NFT Transfer VAAs are retrieved from the Guardian Network by the `emitterChainID`, `emitterAddress`, and `sequence`_
```
const emitterAddr = getEmitterAddressEth(network.NFTBridgeAddress);
const seq = parseSequenceFromLogEth(tx, network.bridgeAddress);
const vaaURL = `${config.wormhole.restAddress}/v1/signed_vaa/${network.wormholeChainId}/${emitterAddr}/${seq}`;
let vaaBytes = await (await fetch(vaaURL)).json();
while (!vaaBytes.vaaBytes) {
console.log("VAA not found, retrying in 5s!");
await new Promise((r) => setTimeout(r, 5000)); //Timeout to let Guardiand pick up log and have VAA ready
vaaBytes = await (await fetch(vaaURL)).json();
}
```
3. Complete the NFT transfer by submitting the resultant VAA to the target chain.
```
completeTransfer(VAA);
```
<!---
TODO
additional usecases, most specifically how to grab the origin address of the wrapped NFT
-->

16
src/technical/evm/overview.md Normal file
View File

@ -0,0 +1,16 @@
# EVM
**Disclaimer**: This section is written as a guide for how to use Wormhole for experienced EVM developers. If you are new to using the EVM ecosystem, it's recommended for you to get started with a tutorial like [this]().
For our purposes, EVM refers to any blockchain in the Wormhole ecosystem that utilizes EVM contracts of Wormhole -- this includes blockchains beyond Ethereum such as Polygon or Avalanche, as well as EVM+ environments such as Acala.
### Recommended Tooling for EVM
**Frontend Development**
- [Ethers](https://docs.ethers.io/v5/) an excellent, widely used library for using web-based wallets to interact with EVM blockchains.
**Contract Development and Testing**
- [Foundry](https://github.com/foundry-rs/foundry) is the preferred library for the Core Repository. It has tooling for development, testing, compilation, and even the ability to duplicate mainnet environments for development.
- [Truffle](https://trufflesuite.com/) and [Hardhat](https://hardhat.org/) are also viable alternatives.

1
src/technical/evm/relayer.md Normal file
View File

@ -0,0 +1 @@
# Relayer Module

135
src/technical/evm/xassetLayer.md Normal file
View File

@ -0,0 +1,135 @@
# Token Bridge
This section will explain how to properly interact with the Wormhome Token Bridge Module in an EVM ecosystem.
## Configuring the interface
[Here]() is the interface for applications to interact with Wormhole's Token Bridge.
//TODO link to file in github so doesn't become stale
Instantiating the interface will depend on your development ecosystem and blockchain. The Wormhole Token Bridge contract address is usually stored in your contract address.
Below is an example line of code to instantiate the interface for mainnet Ethereum:
```
address private wormhole_token_bridge_address = address(0x3ee18B2214AFF97000D974cf647E7C347E8fa585);
ITokenBridge token_bridge = ITokenBridge(wormhole_token_bridge_address);
```
## Registering New Tokens
Attesting a token from EVM needs to happen once per token. If a token is not attested, it will not be claimable until so. However, there are no restrictions to reattesting a token; doing so will update the metadata.
It is not advised to attest tokens on-chain for most usecases. To attest a token by an off-chain process, you can either do it by hand through one of the Token Bridge UIs (for example [Portal](https://www.portalbridge.com/#/register)) or using the [JS SDK](https://www.npmjs.com/package/@certusone/wormhole-sdk).
_[Here](../../development/portal/evm/attestingToken.md) is an example of how to attest a token using the JS SDK._
## Basic Transfer
Basic transfer should only be used if you are transferring messages to an end user wallet. If the end destination is a contract, you should only use Contract Controlled Transfers (described below).
It is important to note the transferring native currency is a special case of the Basic Transfer. As such, a different function call is provided as a QoL improvement when initiating and completing the transfer messaging when unwrapping the ETH is desired.
To transfer a token, there are four steps:
1. Approve the Token Bridge to spend that token on our behalf.
- _Note: Tokens in EVM usually denote up to 18 decimals places. However. Wormhole normalizes this to **8** decimals._
```
contractAddress.approve(token_bridge_address, amt);
```
2. Transfer the token to create the transfer VAA.
- This function call will return a `sequence` (uint64) that is used in the VAA retrieval step.
- _Note: Wormhole addresses are 32 bytes for standardization across the different blockchains within the Wormhole ecosystem._
```
// To initiate transfer of normal ERC-20s
token_bridge.transferTokens(tokenAddress, amount, recipientChain, recipient, arbiterFee, nonce);
// To initiate transfer of native currency
token_bridge.wrapAndTransferETH(recipientChain, recipient, arbiterFee, nonce);
```
3. Retrieve the emitted VAA.
- _Note: Basic Transfer VAAs are retrieved from the Guardian Network by the `emitterChainID`, `emitterAddress`, and `sequence`_
```
const emitterAddr = getEmitterAddressEth(network.tokenBridgeAddress);
const seq = parseSequenceFromLogEth(tx, network.bridgeAddress);
const vaaURL = `${config.wormhole.restAddress}/v1/signed_vaa/${network.wormholeChainId}/${emitterAddr}/${seq}`;
let vaaBytes = await (await fetch(vaaURL)).json();
while (!vaaBytes.vaaBytes) {
console.log("VAA not found, retrying in 5s!");
await new Promise((r) => setTimeout(r, 5000)); //Timeout to let Guardiand pick up log and have VAA ready
vaaBytes = await (await fetch(vaaURL)).json();
}
```
4. Complete the transfer using the VAA.
```
// To complete transfer of normal ERC-20s
token_bridge.completeTransfer(VAA);
// To complete transfer of native currency
completeTransferAndUnwrapETH(VAA);
```
## Contract Controlled Transfer
For any message transfers where the destination is a contract, you should always used Contract Controlled Transfers.
There are a few main differences between Contract Controlled Transfers and Basic Transfers:
- message contains both tokens and an arbitrary payload
- can only be redeemed by a specified contract address
- does not have a relayer fee field because of the redemption restriction above.
As was the case with Basic Transfers, transferring native currency is a special case for Contract Controlled Transfers as well. As such, a different function call is provided as a QoL improvement when initiating and completing the transfer messaging when unwrapping the ETH is desired.
The process of sending a Contract Controlled Transfer is very similar to that of a Basic Transfer:
1. Approve the Token Bridge to spend that token on our behalf.
- _Note: Tokens in EVM usually denote up to 18 decimals places. However. Wormhole normalizes this to **8** decimals._
```
contractAddress.approve(token_bridge_address, amt);
```
2. Transfer the token to create the transfer VAA.
- This function call will return a `sequence` (uint64) that is used in the VAA retrieval step.
- _Note: Wormhole addresses are 32 bytes for standardization across the different blockchains within the Wormhole ecosystem._
```
// To initiate transfer of normal ERC-20s
token_bridge.transferTokesWithPayload(tokenAddress, amount, recipientChain, recipient, nonce, payload);
// To initiate transfer of native currency
token_bridge.wrapAndTransferETHWithPayload(recipientChain, recipient, nonce, payload);
```
3. Retrieve the emitted VAA.
- _Note: Basic Transfer VAAs are retrieved from the Guardian Network by the `emitterChainID`, `emitterAddress`, and `sequence`_
```
const emitterAddr = getEmitterAddressEth(network.tokenBridgeAddress);
const seq = parseSequenceFromLogEth(tx, network.bridgeAddress);
const vaaURL = `${config.wormhole.restAddress}/v1/signed_vaa/${network.wormholeChainId}/${emitterAddr}/${seq}`;
let vaaBytes = await (await fetch(vaaURL)).json();
while (!vaaBytes.vaaBytes) {
console.log("VAA not found, retrying in 5s!");
await new Promise((r) => setTimeout(r, 5000)); //Timeout to let Guardiand pick up log and have VAA ready
vaaBytes = await (await fetch(vaaURL)).json();
}
```
4. Complete the transfer using the VAA.
```
// To complete transfer of normal ERC-20s
token_bridge.completeTransferWithPayload(VAA);
// To complete transfer of native currency
completeTransferAndUnwrapETHWithPayload(VAA);
```

0
src/technical/relayer/genericRelayer.md Normal file
View File

4
src/technical/relayer/overview.md Normal file
View File

@ -0,0 +1,4 @@
# Relayer Development
This section will help you get started with specialized relayer development
generic relayers only require on-chain components. If you're using those, everything you need should be encompassed by referencing the relevant 'Relayer Module' sections above.

1
src/technical/relayer/pluginRelayers.md Normal file
View File

@ -0,0 +1 @@
# Specialized Relayers

25
src/technical/relayer/specializedRelayers.md Normal file
View File

@ -0,0 +1,25 @@
- Link to Plugin relayer codebase
- Recommend plugin relayers as the starting point for anyone developing specialized relayers
- plugin relayers provide a kernel for relayer development. Handles management of all the necessary hotwallets, provides the necessary typescript interfaces for dealing with each ecosystems, and provides an easy integration point to connect to the guardian network
- Follow the instructions provided in the codebase in order to get it running
- to develop a plugin, simply implement the interface provided at [here]
- diagram explaining the flow
- Listener component listens to either incoming REST calls or the guardian network for relevant VAAs,
- When a relevant VAA is detected, your listener code is responsible for producing an action.
- This action is stored in a redis instance
- The executor portion of the interface is responsible for consuming interactions which are provided by the listener.
- The executor is handed an action and is responsible for consuming that action and (optionally) queuing up more actions
- additional configuration info can be found in the README of the codebase.
# Homerolling a Relayer
If you're totally homerolling a relayer solution, you'll need to interact with the guardian network directly.
link to spydk. Use this to tie directly into the guardian network and receive events. If you're particularly ambitious, you can even join the guardian network as a 'spy' which is the term for a non-validating guardian.
VAAs can also be pulled directly from any public node on the guardian network using REST endpoints. This is a really simple way to grab known VAAs.
- provide the REST endpoints for this

0
src/technical/solana/core.md Normal file
View File

0
src/technical/solana/nft.md Normal file
View File

0
src/technical/solana/xasset.md Normal file
View File

4
src/wormhole/1_whatIsWormhole.md
View File

@ -1,6 +1,6 @@
# What is Wormhole?
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.
Wormhole V1 was introduced in 2020 by Certus One, and was initially conceived as a traditional token bridge between Ethereum and Solana. It served as the first bridge on Solana and was responsible for bootstrapping a large amount of the liquidity in the early Solana and Serum ecosystems.
However, despite its beginnings as a token bridge, Wormhole quickly grew beyond Solana and token transfers.
@ -10,4 +10,6 @@ Over the past year, Wormhole has evolved to support an ever-growing list of bloc
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 cross-chain functionality required to develop xDapps.

24
src/wormhole/2_architectureOverview.md
View File

@ -2,7 +2,7 @@
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.
![Architecture Diagram](../diagrams/images/architecture-2022-01-02-1935.png)
![Architecture Diagram](../diagrams/images/architecture.png)
### On-Chain Components
@ -10,13 +10,15 @@ Wormhole is a complex ecosystem with several noteworthy components. Before we go
- **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.
- **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.
- **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.
- **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.
- **Gas Oracle** - _in development\*_ - Oracle for recommended fair gas prices across the ecosystem.
- **Worm Router Contracts** - _in development\*_ - Contracts that allow developers to make their Dapp an xDapp that users on any Wormhole supported chain can interac with purely through clientside code.
### Off-Chain Components
@ -26,12 +28,16 @@ Wormhole is a complex ecosystem with several noteworthy components. Before we go
- **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.
- **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.
- **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.
- **Specialized Relayers** - Relayers that only handle VAAs for a specific protocol or xDapp. They can 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.
- **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.
- **Wormchain** - _in development\*_ - A purpose-built cosmos blockchain which aids the Guardian Network and allows for formal interaction with the Guardians.
\*\*Features listed as _in development_ are not yet available in mainnet.
\*Features listed as _in development_ are not yet available.
---
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.

20
src/wormhole/3_coreLayerContracts.md
View File

@ -4,11 +4,11 @@ The Core Contracts are the mechanism by which all Wormhole messages are emitted.
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.
In general, Core Contracts are simple with only a few public-facing functions, which we'll define next.
In general, Core Contracts are simple and can be broekn down to a **sending** and **receiving** side, which we'll define next.
---
### Sending
First, we have the 'sending' side of the Core Contract:
Below is the mechanism by which Wormhole messages (aka Verified ACtion Approval, VAA) are emitted:
publishMessage(
int nonce,
@ -16,23 +16,23 @@ First, we have the 'sending' side of the Core Contract:
int consistencyLevel
) returns int sequenceNumber
This is the foundational mechanism by which Wormhole Messages are emitted. Let's break it down a bit:
Let's break it down a bit:
- **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.
- **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.
- **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.
- **nonce** - An index number for the message that is used to produce Batch VAAs. How this is generated is elaborated in the [CoreLayer](../technical/evm/coreLayer.md) section.
- **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.
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 and the message passes all of the Guardians' optional checks, 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.
---
### Receiving
Next, we have the 'receiving' side of the Core Contract.
Below is the mechanism by which VAAs are received:
parseAndVerifyVAA( byte[] VAA )
@ -48,8 +48,10 @@ VAAs simply attest that "this contract on this chain said this thing." Therefore
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 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.
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 Token Bridge & the Relaying contract) handle this on behalf of downstream consumers.
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 our next section, we'll dive into the technical specfications of the VAA.

24
src/wormhole/4_vaa.md
View File

@ -27,13 +27,31 @@ The Body is the relevant information for consumers and is handed back from parse
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 place.
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. If a VAA has a specific destionation, it is entirely the responsibility of relayers to complete that delivery appropriately.
## 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 simplifies the process of relaying and consuming multiple VAAs.
Certain blockchains support version 2 VAAs, also referred to as **Batch VAAs** which are designed to provide an easier paradigm for composability and better gas efficiency when multiple cross-chain actions are involved in a single transaction.
Batch VAAs are not currently live on mainnet, but will have initial support on all EVM chains when they launch.
Batch VAAs are designed to be automatically generated for all messages that come from a single transaction.
In an extreme composability scenario or advanced integration, there may be some messages in a transaction that may not be relevant to one another. To control the create of additional batches, some messages can be created with the same `nonce` to _additionally_ group them.
It is of note that Single VAAs will always be emitted for each message generated, regardless of it they are contained in a Batch VAA or not.
Go [here](../technical/evm/coreLayer.md) for a more detailed description of how Batch VAAs are generated.
_Note: Batch VAAs are not currently live on mainnet, but will have initial support on all EVM chains when they launch._
> How to leverage Batch VAAs
>
> Imagine a transaction generates three messages (A, B, C) that a consuming contract needs to know about.
>
> If each message is independent of each other, the consuming contract can handle and validate each of these VAAs individually like [A], [B], [C].
>
> If all of the messages are related to each other, the consuming contract can handle and validate the Batch VAA of the entire transaction that is automatically generated like [A, B, C].
>
> If only two of the messages are related to each other, say A and C, the same `nonce` can be used for those two messages to generate an additional Batch VAA and the consuming contract can then handle and validate two sets of VAAs like [A, C] and [B].
---

2
src/wormhole/5_guardianNetwork.md
View File

@ -58,4 +58,6 @@ However, once all the full nodes are running, the actual computation and network
Over time, the Guardian Set can be expanded beyond 19 with the use of threshold signatures. A variety of relaying models will emerge, each with their own strengths and weaknesses. ZKPs can be used on chains where they are well supported. The xDapp ecosystem will grow, and xDapps will become increasingly intermingled with eachother. There are very few APIs in Wormhole, and most items are implementation details from the perspective of an integrator. This creates a clear pathway towards a fully trustlessness interoperability layer which spans the entirety of decentralized computing.
---
In the next section, we will talk about the role and responsbilities of relayers in the Wormhole ecosystem.

44
src/wormhole/6_relayers.md
View File

@ -1,6 +1,12 @@
# 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' portion.
All simple cross-chain processes on Wormhole essentially boil down to a three step process:
1. Perform an action on chain A.
2. Retrieve the resulting VAA from the Guardian Network.
3. Perform an action on chain B using the VAA.
Relayers play a key role in the final step of the process -- they can be thought of as the 'write' portion of interoperability, complementing the 'read' portion that Guardians provide.
The definition of a _Relayer_ in the context of Wormhole is: Any process which delivers VAAs to a destination.
@ -18,31 +24,27 @@ Next, we'll go over a few of the most common relaying strategies.
## Client-side Relaying
All simple processes on Wormhole essentially boil down to a three step process:
Client-side relaying relies on the user-facing frontend, like a webpage or a wallet, to perform all three steps of the cross-chain process.
1. Perform an action on chain A.
2. Retrieve the resulting VAA from the Guardian Network.
3. Perform an action on chain B using the VAA.
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:
There are two major benefits of this approach:
- Low cost. Users pay exactly the transaction fee for the second transaction.
- No backend relaying infrastructure.
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:
However, client-side relaying also has two notable drawbacks:
- 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. 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 but can be useful to getting an MVP up and running.
## 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.
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 (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 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.
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 developers should not rely on off-chain relayers to perform any computation which is considered "trusted." However, things that do not impact security like deterministic data transforms, waiting for gas prices to drop, or various forms of 'batching' can be very useful cost-reduction strategies.
Specialized Relayers have the following advantages:
@ -55,11 +57,19 @@ However, they also have a couple notable downsides
- 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. This is similar to how dependencies like the frontend, blockchain nodes, blockchains, third party APIs, etc, can also cause outages.
Due to specialized relayers being such a common solution, an extensible relayer (called the plugin relayer) has been provided in the main Wormhole repository. The plugin relayer stands up most of the requisite infrastructure for relaying, so that you only need to implement the logic which is specific to your application.
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.
If you plan to develop a specialized relayer, consider starting from the plugin relayer [found here](https://github.com/wormhole-foundation/wormhole/tree/dev.v2/relayer).
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.
<!--
TODO link to plugin relayer once it has been merged down
-->
Because relayers are responsible for liveness, they become another dependency component (similar to the frontend, blockchain nodes, blockchains, third party APIs, etc.) for the xDapp. If the relayers are all down, your application has an outage.
To mitigate this, multiple relayers can be run in order to provide redundancy either by (1) the xDapp team or (2) a decentralized network based off economic incentives. _However, creating a robust model for decentralized relaying is generally application-specific and complex._
Overall, Specialized Relayers add a backend component that is responsible for liveness, but can simplify the user experience. It's generally recommend if your goal is a highly-polished user experience and you want to have better control over message delivery.
# Generic Relayers
@ -77,9 +87,11 @@ Generic relayers have the following benefits:
And potential downsides:
- They require all calculations to be done on-chain
- They have less gas efficiency
- They sometimes have less gas efficiency
- They may not be supported on all chains
Overall, Generic Relayers simplify both the developer and user experience. They're a great choice if they cover all your usecases.
---
In the next section, we'll discuss the Portal Ecosystem contracts that allow xAssets to be created and moved freely around the ecosystem.
In the next section, we'll discuss the xAsset module, which allows xAssets to be created and moved freely around the ecosystem.

79
src/wormhole/7_TokenBridge.md Normal file
View File

@ -0,0 +1,79 @@
# xAsset Layer
There is a set of ecosystem contracts that provision Wormhole's xAsset layer which allow tokens to be bridged around the Wormhole Ecosystem in a **path-independent** fashion, and are easily composable with other functions in the Wormhole ecosystem.
This section provides a high-level overview of how to interact with two smart contract modules that implement xAssets: (1) Token Bridge module and (2) NFT Bridge Module.
If you're looking to interact with the Token Bridge directly from a typescript client or backend, you should start with the [Wormhole Typescript SDK](https://www.npmjs.com/package/@certusone/wormhole-sdk).
## Creating xAssets
xAssets always have an **origin chain**. This is where the token is initially minted via the standard of that chain (ERC-20, SPL, etc for tokens; ERC-721, Metaplex, etc for NFTs).
xAssets are all **fungible** with each other. This means the Wormhole-wrapped asset can be exchanged for the original asset or a wrapped asset from other chains.
**Tokens**
To convert tokens 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,
uint32 nonce)
returns (uint64 sequence)
The Guardian Network will then produce an **attestation VAA**, which can be retrieved using the sequence number returned by the attestToken function.
The attestation VAA must then be submitted to the **createWrapped** function of every other chain, referred to as **foreign chains** for this token.
function createWrapped(
bytes memory encodedVm)
returns (address token)
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.
**NFTs**
NFTs do not need need to be attested before they can be created into a xAsset.
## Transferring xAssets
Initiating xAsset 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 the Token Bridge are backed by the origin asset, allowing assets to be transferred in a path-independent fashion. Regardless of what chain the assets are passed to, a 'double-wrapped' asset will never be created for a single backing asset. Additionally, there are no liquidity limitations.
**Tokens**
```
function transferTokens(
address token,
uint256 amount,
uint16 recipientChain,
bytes32 recipient,
uint256 arbiterFee,
uint32 nonce) returns (uint64 sequence)
```
**NFTs**
```
function transferNFT(
address token,
uint256 tokenID,
uint16 recipientChain,
bytes32 recipient,
uint32 nonce) returns (uint64 sequence)
)
```
## Contract-Controlled Transfers
Basic transfers are intended to transfer xAssets from one wallet to another, whereas Contract Controlled Transfers (CCTs) are meant to transfer xAssets from one smart contract to another. If you're writing an xDapp, CCTs will likely be a large component.
CCTs allow xDapp contracts to easily perform simple xAsset 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 the next section, we'll discuss Wormchain and some of the upcoming features it will enable.

53
src/wormhole/7_portalTokenBridge.md
View File

@ -1,53 +0,0 @@
# Portal xAsset Bridge
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.
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 where the token is initially minted via the standard of that chain (ERC-20, SPL, etc).
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,
uint32 nonce)
returns (uint64 sequence)
The Guardian Network will then produce an **attestation VAA**, which can be retrieved using the sequence number returned by the attestToken function.
The attestation VAA must then be submitted to the **createWrapped** function of every other chain, referred to as **foreign chains** for this token.
function createWrapped(
bytes memory encodedVm)
returns (address token)
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 each other. This means the Wormhole-wrapped token can be exchanged for the original token or wrapped tokens from other chains.
## Transferring Assets
function transferTokens(
address token,
uint256 amount,
uint16 recipientChain,
bytes32 recipient,
uint256 arbiterFee,
uint32 nonce) returns (uint64 sequence)
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, 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
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.
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 the next section, we'll discuss Wormchain and some of the upcoming features it will enable.

2
src/wormhole/8_wormchain.md
View File

@ -13,4 +13,6 @@ Wormchain is built to provide things like:
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.