Merge branch 'mvp' of github.com:certusone/xdapp-book into mvp

book.toml

@@ -1,8 +1,12 @@
 [book]
-title = "xDapp Book 0.1.0"
+title = "Wormhole xDapp Development Book v0.1.0"
 authors = [
     "Dev Bharel"
 ]
 language = "en"
 multilingual = false
-src = "src"
+src = "src"
+
+[output.html]
+default-theme= "ayu"
+git-repository-url="https://github.com/certusone/xdapp-book"

src/SUMMARY.md

@@ -14,15 +14,15 @@
   - [What is an xDapp?](./dapps/4_whatIsanXdapp.md)
   - [Advantages of xDapps](./dapps/5_advantages.md)
 
-- [Wormhole](./wormhole/wormholeOverview.md)
-  - [What is Wormhole?](./wormhole/whatIsWormhole.md)
-  - [Architecture Overview](./wormhole/architectureOverview.md)
-  - [Guardian Network](./wormhole/guardianNetwork.md)
-  - [Core Layer Contracts](./wormhole/coreLayerContracts.md)
-  - [VAA: Verifiable Action Approval](./wormhole/vaa.md)
-  - [Relayers](./wormhole/relayers.md)
-  - [Portal xAsset Bridge](./wormhole/portalTokenBridge.md)
-  - [Wormchain](./wormhole/wormchain.md)
+- [Wormhole](./wormhole/0_wormholeOverview.md)
+  - [What is Wormhole?](./wormhole/1_whatIsWormhole.md)
+  - [Architecture Overview](./wormhole/2_architectureOverview.md)
+  - [Core Layer Contracts](./wormhole/3_coreLayerContracts.md)
+  - [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)
+  - [Wormchain](./wormhole/8_wormchain.md)
 
 ---
 

src/dapps/0_xdappOverview.md

@@ -1,3 +1,5 @@
+# An Introduction to xDapps
+
 As a first order of business, let's go over the current state of the De-Fi ecosystem, the emerging role of xDapps, and what advantages they have over conventional Dapps.
 
 By the end of this chapter, you should have a clear understanding of what xDapps are, and why they are gaining so much traction in the blockchain development community.

src/dapps/1_defiBasics.md

@@ -18,7 +18,7 @@ In the introvening years, a rich ecosystem of Dapps has cropped up across the my
 
 However, today's Dapps are not without their limitations, and many of these limitations are tied to the underlying blockchains themselves.
 
-Two key limitations of baseline blockchain technology is that it has no access to off-chain data, and also no mechanism to interact with other blockchains. These limitations have lead to a fractured ecosystem, where each blockchain is - by default - siloed off from the others. Assets native to Polygon are not accessible on Ethereum, and services like Uniswap can't be leveraged on Solana.
+Two key limitations of blochains are that they have no access to off-chain data, and also no mechanism to interact with other blockchains. These limitations have lead to a fractured ecosystem, where each blockchain is - by default - siloed off from the others. Assets native to Polygon are not accessible on Ethereum, and services like Uniswap can't be leveraged on Solana.
 
 This is obviously not a desireable state of the world, and blockchain developers are now aiming to solve these interoperability problems in order to create a better, more unified ecosystem where the gory details of each blockchain are abstracted away. In this new cross-chain ecosystem, people stop being "Ethereum" or "Solana" users, and simply become Web3 users.
 

src/dapps/2_crossChainInteroperability.md

@@ -11,15 +11,15 @@ Centralized Exchanges play an important role in the cryptocurrency space, but th
 1. They're centralized, which directly defeats the purpose of creating a decentralized platform in the first place.
 2. They deal only with tokens. As blockchains move away from being a simple history of token transfers, and towards being general purpose computing platforms, interoperability will involve much more complex data structures than 'tokens', and much more sophisticated operations than 'transfers'.
 
-To solve the centralization problems associated with CEXs, the DEX was born. A DEX operates inside a smart contract runtime, and therefore can be as decentralized as the blockchain it runs on. Unfortunately, a DEX is only able to utilize the tokens which exist on its native blockchain, so in order to obtain a token which is not native to the blockchain, the DEX must be used in combination with a **bridge**.
+To solve the centralization problems associated with CEXs, decentralized exchanges (DEXs) were created. A DEX operates inside a smart contract runtime, and therefore can be as decentralized as the blockchain it runs on. Unfortunately, a DEX is only able to utilize the tokens which exist on its native blockchain, so in order to obtain a token which is not native to that chain, the DEX must be used in combination with a **bridge**.
 
 **Bridges** are a complex beast which will be discussed in depth later. For now, we can simply categorize bridges as applications which 'lock' assets on one chain in exchange for **wrapped assets** on another chain. The wrapped assets can, in turn, be exchanged for the original 'backing' asset.
 
 Here are some other key things to understand about bridges:
 
 - Bridges are currently the only way to custody a token on a chain other than its 'native' chain. If you're holding ETH on some chain other than Ethereum, it is, _by definition_, a wrapped token.
-- Generally, wrapped tokens become 'double wrap' when they traverse multiple bridges or blockchains. This creates a lengthy unwrapping process to get back to the original token.
-- Bridges are all mutually incompatible with eachother.
+- Generally, wrapped tokens become 'double wrapped' when they traverse multiple bridges or blockchains. This requires an annoying unwrapping process to get back to the original token.
+- Bridges are all mutually incompatible with eachother. Using multiple bridges just makes double wrapped tokens.
 - Bridges are capable of being decentralized in theory, but are often quite centralized in practice.
 
 This brief history explains how we arrived at where we are today. CEXs are a simple solution to siloed blockchains, DEXs are a simple response to CEXs, and once you have DEXs, bridges become necessary infrastructure. 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 a result of this.
@@ -28,4 +28,4 @@ The way to address these issues is not to slap another bandage on top, but rathe
 
 Wormhole is an attempt to do just this. It looks at the budding decentralized computing ecosystem and proposes a new way of developing applications which leverages the strengths of each blockchain while mitigating the problems which have thusfar plagued the ecosystem.
 
-The first step in this endeavor is to dethrone the 'token' as the fundamental atomic unit of blockchains, and instead to think of these platforms as global computers which operate on data. This new atomic unit is called **xData**, and we'll talk more about it in the next section.
+The first step in this endeavor is to dethrone the 'token' as the fundamental atomic unit of blockchains, and instead to think of these platforms as global computers which operate on data. We'll expand upon this in the next section.

src/dapps/3_xdataxassets.md

@@ -1,6 +1,6 @@
 # xData and xAssets
 
-One of the biggest items on the wishlist of features for blockchains is the ability to detach tokens from their native chains. It is a tremendous limitation that ETH only exists on Ethereum, MATIC only exists on Polygon, and SOL only exists on Solana. It would be much more convenient if those assets existed independently of their blockchains, and were able to move freely.
+One of the biggest items on the wishlist of features for blockchains is the ability to detach tokens from their native chains. It is a tremendous limitation that ETH only exists on Ethereum, MATIC only exists on Polygon, and SOL only exists on Solana. It would be far more convenient if those assets existed independently of their blockchains, and were able to move freely.
 
 This is the concept of an **xAsset**, and it should be thought of as the next-generation _wrapped token_. The key feature of an xAsset is that it is chain and path agnostic, and thus retains fungibility regardless of where it travels. xAssets can move fluidly around the blockchain ecosystem without ever becoming double-wrapped. In a sense, xAssets are abstracted to a layer _outside_ of the blockchain ecosystem, and are then able to transact on whatever blockchain is most sensible.
 

src/misc/doubleAck.md

@@ -0,0 +1,12 @@
+Step 1:
+
+Escrow required funds on chain A, send proposal VAA
+
+Step 2:
+
+If proposal VAA is accepted, escrow the required funds on B and send an ACK VAA
+Otherwise, send a NACK
+
+Step 3:
+If NACK is received, roll back to state zero.
+If a sufficient timeout is exceeded, roll back to state zero

src/wormhole/0_wormholeOverview.md

@@ -0,0 +1,5 @@
+# Wormhole
+
+In the previous chapter, we established concepts like xDapps, xData, and xAssets. In this chapter, we'll dive into the inner workings of the Wormhole ecosystem, and how they give rise to these ideas.
+
+By the end of this chapter, you should have a clear understanding of what Wormhole is, what its key components are, and how each of those components comes together to create a powerful, new cross-chain ecosystem.

src/wormhole/1_whatIsWormhole.md

@@ -0,0 +1,13 @@
+# What is Wormhole?
+
+Wormhole was first conceived in 2020 by Certus One, and was initially scoped as a traditional token bridge between Ethereum and Solana. The Wormhole v1 Token Bridge was the first bridge on Solana, and was responsible for bootstrapping a large amount of the liquidity in the early Solana and Serum ecosystems.
+
+Despite its beginnings as a token bridge, Wormhole quickly grew beyond Solana, and beyond the domain of token transfers.
+
+Wormhole v2 launched in August 2021 as a decentralized generic interoperability protocol for multiple blockchain ecosystems, with initial support for Solana, Terra, Ethereum, and Binance Smart Chain.
+
+Over the past year, Wormhole has grown to support an ever-growing list of blockchains, across an unrivaled number of smart contract runtimes.
+
+While Wormhole is a generic interoperability protocol, it is also an ecosystem and platform for developers to grow the decentralized computing space. Wormhole consists of multiple modular swap-in components which can be leveraged independently, and supports a growing number of composible applications built by numerous teams.
+
+In the next section, we'll go over the major components of the Wormhole ecosystem, and how they fit together to enable the high-level cross chain functionality required to develop xDapps.

src/wormhole/2_architectureOverview.md

@@ -0,0 +1,33 @@
+# Architecture Overview
+
+Wormhole is a fairly complex ecosystem, with several noteworthy components. Before we go in depth into each component, let's take a moment to lay out the names of the major pieces, and how they fit together.
+
+![Architecture Diagram](../diagrams/images/architecture-2022-01-02-1935.png)
+
+### On-Chain Components
+
+- **xDapp Contracts** - these are contracts developed by xDapp developers. They receive transactions from the end user, and then interact with other xDapp contracts and Wormhole Ecosystem Contracts in order to provide their service.
+- **Ecosystem Contracts** - these are contracts inside the Wormhole Ecosystem, subject to Wormhole governance. Their job is to provide the feature suite of Wormhole to xDapp developers.
+
+  - **Core Contracts** - these are the primary ecosystem contracts. These are the contracts which the Guardians observe, and which fundamentally allow for cross-chain communication.
+  - **Portal xAsset Contracts** - these contracts allow normal tokens to be converted to xAssets, and enable these xAssets to be bridged around the ecosystem.
+  - **Relay Contracts** - _in development\*_ - allow xDapps to send messages to a specific blockchain, via the use of the decentralized Generic Relayer network.
+  - **Gas Oracle** - _in development\*_ - oracle for recommended fair gas prices across the ecosystem.
+
+### Off-Chain Components
+
+- **Guardian Network** - Guardians exist in their own p2p network. They observe the Core Contract on each supported chain, and produce VAAs (signed messages) when those contracts receive an interaction.
+
+  - **Guardian** - One of the validators in the Guardian Network which contributes to the VAA multisig. There are currently exactly 19 Guardians.
+
+  - **Spy** - Validators on the Guardian Network which are not part of the Guardian set. These spies can observe and forward network traffic, which helps scale up VAA distribution.
+
+  - **Wormchain** - _in development\*_ - a purpose built cosmos blockchain which aids the Guardian Network, and allows for formal interaction with the Guardians.
+
+- **Specialized Relayers** - relayers which only handle VAAs for a specific protocol or xDapp. This allows them to execute custom logic off-chain, which can reduce gas costs and increase cross-chain compatibility. Currently, xDapp developers are responsible for developing and hosting this component.
+
+- **Generic Relayers** - _in development\*_ - a decentralized relayer network which delivers messages that are requested on-chain via the Wormhole Relay Contract.
+
+- **VAAs** - Verifiable Action Approvals - These are the key piece of data in the Wormhole ecosystem. They contain the messages which are emitted by xDapps, along with information such as what contract emitted the message. The VAAs are signed by the Guardians, and need 13/19 signatures in order to be considered authentic.
+
+\*\*Features listed as _in development_ are not yet available in mainnet.

src/wormhole/3_coreLayerContracts.md

@@ -0,0 +1,51 @@
+# Core Contracts
+
+The Wormhole Core Contracts are one of the most pivotal pieces of the Wormhole ecosystem, and serve as a great place to start when learning about how data flows through the ecosystem.
+
+There is one Core Contract on each blockchain in the ecosystem, and this is the contract which the Guardians are required to observe. The Core Contracts are the mechanism by which all Wormhole messages are emitted. All xDapps either interact directly with the Core Contract, or interact with some other contract which does.
+
+The Core Contracts are quite simple and only have a few public-facing functions.
+
+---
+
+    publishMessage(
+        int nonce,
+        byte[] payload,
+        int consistencyLevel
+    ) returns int sequenceNumber
+
+This is the mechanism by which Wormhole Messages are emitted.
+
+- **payload** is an arbitrary byte array, and is the content of the emitted message. It may be capped to a certain maximum length due to the constraints of individual blockchains.
+- **consistencyLevel** is the number of blocks which the guardians should wait prior to emitting a VAA for this message. This number is usually either 1, or equal to the chain's finality period. This is a defense against transactions being orphaned.
+- **nonce** - on chains where batch VAAs are supported, if multiple messages in the same transaction have the same nonce, a batch VAA will be produced alongside the individual VAAs. This feature reduces gas costs and simplifies composeability.
+
+- **sequenceNumber** - this is a unique index number for the message. When combined with the emitter contract address and emitter chain ID, the corresponding VAA can be retrieved from a guardian network node.
+
+The implementation strategy for publishMessage differs by chain. However, the general strategy is that the Core Contract will post the emitterAddress (the contract which called publishMessage), sequenceNumber, and consistencyLevel into the blockchain logs. Once the desired consistencyLevel has elapsed, the Guardian Network will produce the requested VAAs.
+
+Currently there are no fees to publish a message, except when publishing on Solana. This is not guaranteed to always be the case, however.
+
+---
+
+Second, we have 'receiving' side of the Core contract.
+
+    parseAndVerifyVAA( byte[] VAA )
+
+This function, when passed a VAA, will either return the payload and associated metadata for the VAA, or throw an exception. An exception should only ever throw if the VAA fails signature verification, which would indicate that the VAA is invalid or inauthentic in some form.
+
+---
+
+## Multicasting
+
+Let's take a moment to point out that there is no inclusion of any destination address or chain in these functions.
+
+VAAs simply attest that "This contract on this chain said this thing". Therefore, VAAs are multicast by default, and will be verified as authentic on any chain they are brought to.
+
+This multicast-by-default model is intentional, and also integral to the design. Having this multicast capacity makes it easy to synchronize state across the entire ecosystem, because a single blockchain can make its data available to every chain in a single action with low latency. This, in turn, reduces the complexity of the n^2 problems encountered by routing data to a large number of blockchains.
+
+Usecases where the message has an intended recipient or is only meant to be consumed once must be handled in logic outside the Core Contract. There are standard practices for accomplishing these features shown later on in the code examples, and some ecosystem contracts (namely Portal & the Relaying contract) handle this on behalf of downstream consumers.
+
+Lastly, because the VAA creation is a separate concern from relaying, there is _no additional cost_ to this multicast model when a single chain is being targetted. If the data isn't needed on a certain blockchain, don't relay it there, and it won't cost anything.
+
+In the next section we'll dive into the technical specfications of the VAA.

src/wormhole/4_vaa.md

@@ -0,0 +1,40 @@
+# VAAs (Verified Action Approval)
+
+VAAs are the core messaging primative in Wormhole. You can think of them as packets of xData. Any time an xDapp contract interacts with the Core Contract, a VAA is emitted.
+
+The basic VAA has two components, a Header and a Body.
+
+## Header
+
+    byte        version                  (VAA Version)
+    u32         guardian_set_index       (Indicates which guardian set is signing)
+    u8          len_signatures           (Number of signatures stored)
+    [][66]byte  signatures               (Collection of ecdsa signatures)
+
+The header is used by the Core Contract to determine the authenticity of the VAA, but can generally be ignored by other consumers.
+
+## Body
+
+    u32         timestamp                 (Timestamp of the block where the source transaction occurred)
+    u32         nonce                     (A grouping number)
+    u16         emitter_chain             (Wormhole ChainId of emitter contract)
+    [32]byte    emitter_address           (Emitter contract address, in Wormhole format)
+    u64         sequence                  (Strictly increasing sequence, tied to emitter address & chain)
+    u8          consistency_level         (How many blocks were waited before emitting this VAA)
+    []byte      payload                   (VAA message content)
+
+The body is the relevant information for consumers, and is handed back from parseAndVerifyVAA. Because the emitterAddress is included as part of the body, the developer is able to discern if this VAA originated from a trusted contract.
+
+VAAs are uniquely indexed by their emitterChain, emittedAddress, and sequence. VAAs can be obtained by querying a node in the Guardian Network with this information.
+
+Because baseline VAAs have no destination, they are effectively multicast. They will be verified as authentic by any Core Contract on any chain in the network, and it is entirely the responsibility of relayers to deliver VAAs to the appropriate destination.
+
+## Batch VAAs
+
+Certain blockchains support version 2 VAAs, also referred to as **Batch VAAs**. When multiple messages with the same nonce are emitted in the same transaction, a batch VAA will be created in addition to the individual VAAs. The Batch VAA contains the body of each individual VAA, but only has a single header. This reduces the gas cost of verifying the VAA, and also simplifies the process of relaying and consuming multiple VAAs.
+
+Batch VAAs are not currently live on mainnet, but will have initial support on all EVM chains when they launch.
+
+---
+
+In the next section, we will give an overview of how the Wormhole Guardian network creates these VAAs, and the key design considerations which underpin the network.

src/wormhole/5_guardianNetwork.md

@@ -0,0 +1,61 @@
+# Guardian Network
+
+The Guardian Network is the backbone and most critical component of the Wormhole ecosystem. It is designed to serve as Wormhole's oracle component, and the rest of the Wormhole ecosystem is really founded upon the technical underpinnings of this network. Therefore, this is the single most important component to learn about if you want a deep understanding of Wormhole.
+
+To understand not just _how_ the Guardian Network works, but also _why_ it works the way it does, let's first take a step back, and go over the key considerations which went into the design. There were essentially five critical features which Wormhole needed to have in order to become the best-in-class interoperability platform.
+
+1. **Decentralization** - Control of the network needs to be distributed amongst many parties.
+2. **Modularity** - Disparate parts of the ecosystem such as the oracle, relayer, applications, etc, should be kept as separate and modular as possible so they can be designed, modified, and upgraded independently.
+3. **Chain Agnosticism** - Wormhole should be able to support not only EVM, but also chains like Solana, Algorand, Cosmos, and even platforms which have not even yet been created. It also should not have any one chain as a single point of failure.
+4. **Scalablity** - Wormhole should be able to secure a large amount of value immediately, and should also be able to handle the large transaction volume which will come from high-performance blockchains like Solana.
+5. **Upgradeability** - As the decentralized computing ecosystem evolves and new tech becomes prevalent, Wormhole will need to be able to change the implementation of its existing modules without breaking integrators.
+
+Next, let's go into how Wormhole achieves these one at a time.
+
+## Decentralization
+
+Decentralization is the biggest item. Previous interoperability solutions have largely been entirely centralized, and even newer solutions which utilize things like adversarial relayers still tend to have single points of failure or collusion thresholds as low as 1 or 2.
+
+In designing a decentralized oracle network, the first option to consider is probably a Proof-of-Stake system. However, upon closer inspection, this actually turns out to be a suboptimal solution. PoS is designed for blockchain consensus in smart-contract enabled environments, and it's less suitable when the network is verifying the output of many blockchains and not supporting its own smart contracts. While it looks appealing from a decentralization perspective, the network security is somewhat unclear, and it also makes some of the other outlined goals more difficult to achieve, so let's discuss other options.
+
+The first option would be to rush straight for the finish line, and use zero-knowledge proofs in order to secure the network. This would be the best from a decentralization perspective, as it's literally trustless. However, zero knowledge proofs are still a nascent technology, and it's not really feasible to verify them on-chain, especially on chains with limited computational environments. Thus, some form of multisig will be needed to secure the network.
+
+If we take a step away from game-theoretic considerations of various consensus models and look at the current De-Fi landscape, it's easy to see that most of the top blockchains are secured by the same handful of validator companies. The reality is that at this point in time there are only a limited number of companies in the world with the skills and capital to run top-notch validator companies.
+
+Thus, if a protocol could unite a large number of those validator companies into a purpose-built consensus mechanism which is optimized for chain interoperability, that design would likely be both more performant and more secure than a network which was bootstrapped by a tokenomics model. Assuming the validators would be on board with this idea, how many could Wormhole realistically utilize?
+
+If Wormhole were to use threshold signatures, the answer would basically be 'as many as are willing to participate'. However, threshold signatures have spotty support across the blockchain world, this means it would be difficult and expensive to verify the signatures, which would limit scalability and chain agnosticism. Thus, a t-schnorr multisig is probably the best option as it is cheap and well supported, despite the fact that its verification costs increases linearly with the number of signatures included.
+
+So, with all these things considered, about 19 seems to be the maximum number and a good tradeoff. While it's less ideal than 2000, it's a lot more than most protocols have. 2000 would be infeasible to verify on-chain, and there are not even 2000 top-notch validators in the world today. If 2/3 of the signatures are needed for consensus, then 13 signatures need to be verified on-chain, which remains reasonable from a gas-cost perspective.
+
+Furthermore, rather than securing the network with tokenomics, it is better to initially secure the network by involving robust companies which are heavily invested in the success of De-Fi as a whole. The 19 Guardians are not just anonymous nobodies running their validators out of a basement. They are many of the largest and widely-known validator companies in cryptocurrency. The current Guardians can be viewed [here](https://wormholenetwork.com/network/)
+
+Putting this all together, we end up with 19 Guardians, each with an equal stake, joined in a purpose-built Proof of Authority consensus mechanism. As threshold signatures become better supported, the guardian set can expand, and once ZKPs are ubiquitous, the Guardian Network will become fully trustless.
+
+Now that we have Decentralization laid out, the remaining elements fall into place.
+
+## Modularity
+
+Because the Guardian Network is robust and trustworthy by itself, there is no need for components like the relayer to contribute to the security model. Thus, Wormhole is able to have simple components which are very good at the one thing they do. The Guardians only need to verify on-chain activity and produce VAAs. Relayers only need to concern themselves with how to interact with blockchains and deliver messages.
+
+The signing scheme of the VAAs can be changed without affecting downstream users. Multiple relay mechanisms can exist independently. xAssets can be implemented purely at the application layer. xDapps can utilize whatever components suit them.
+
+## Chain Agnosticism
+
+Wormhole supports a wider range of ecosystems than any other interoperability protocol today. That is largely because it utilizes simple tech (t-schnorr signatures), an adaptable, heterogenous relayer model, and a robust validator network.
+
+Wormhole can expand to new ecosystems as quickly as a Core Contract can be developed for the smart contract runtime. Relayers don't need to be factored into the security model, they just need to be able to upload messages to the blockchain. The Guardians are able to observe every transaction on every chain, without taking shortcuts.
+
+## Scalability
+
+Wormhole scales quite well, as shown by Portal's ability to handle huge TVL and transaction volume, even during tumultuous events such as the UST depeg.
+
+The requirements for running a Guardian are relatively heavy, as they need to run a full node for every single blockchain in the ecosystem. This is another reason why a limited number of robust validator companies are beneficial for this design.
+
+However, once all the full nodes are running, the actual computation and network overheads of the Guardian Network are quite lightweight. As such, the performance of the blockchains themselves tends to be the bottleneck in Wormhole, rather than anything which happens inside the Guardian Network.
+
+## Upgradability
+
+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.

src/wormhole/6_relayers.md

@@ -0,0 +1,89 @@
+# 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'.
+
+The first thing of note is that unlike other interoperability protocols, Wormhole **does not have a required relaying methodology**.
+
+In most designs there is a dedicated relaying mechanism which operates inside the protocol's trust boundaries. This means that the relayer either has an adversarial relationship to the oracle, or the relayer has trust assumptions and contributes to the protocol's security model. Thus, relayers are usually a trusted party, are often also privileged, and you are forced to use the relayer model which is built into the protocol.
+
+In Wormhole, relayers are neither trusted nor privileged. This means relayers **cannot jeopardize security, only liveness**. Because Wormhole is designed to have a firm trust boundary at the level of the VAA, relayers have exactly the same capabilities as any regular, untrusted blockchain user.
+
+From this perspective, relayers are just dumb delivery trucks which deliver VAAs to their destination, and have no capacity to potentially tamper with the delivery outcome. VAAs either get delivered, or don't, which makes relayers analagous to the off-chain 'crank turners' of traditional Dapps.
+
+As a result of this design, Wormhole is able to fascilitate a variety of heterogenous relaying mechanisms, and the developer is able to choose whatever best suit their needs.
+
+The definition of a _Relayer_ in the context of Wormhole is:
+
+    Any process which delivers VAAs to a destination
+
+Next, we'll go over a few of the most common relaying strategies.
+
+## Client-side Relaying
+
+Client side relaying is kind of a good tutorial case, as it's relatively straight forward.
+
+All simple processes on Wormhole essentially boil down to a three step process:
+
+    1. Perform some action on chain A.
+    2. Retrieve the resulting VAA from the Guardian Network.
+    3. Perform some action on chain B using the VAA.
+
+Considering that the first step of this process is almost always initiated from a user-facing frontend such as a webpage or a wallet, it is possible to also perform steps 2 and 3 in the frontend as well. This is referred to as 'client-side relaying', and it has two major benefits:
+
+- Low cost. Users pay exactly the transaction fee for the second transaction.
+- No backend relaying infrastructure.
+
+For this reason, client-side relaying can be a tempting avenue to pursue, especially if you're just interested in getting an MVP running. However, client-side relaying has two notable drawbacks:
+
+- Users must sign all transactions required with their own wallet
+- Users must have funds to pay the transaction fees on every chain involved.
+
+Overall, client-side relaying is a simple solution, but can make the user experience cumbersome. Thus, it's generally not recommended if your goal is a highly-polished user experience.
+
+## 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.
+
+An important consideration when developing a specialized relayer is that the relayer is still considered untrusted. VAAs are totally public, and can be submitted by anyone, so the off-chain relayer should not do any computation which is considered "trusted". However, doing things like deterministic data transforms, waiting for gas prices to drop, or various forms of 'batching' can be very useful cost-reduction strategies which do not impact security.
+
+Specialized Relayers have the following advantages:
+
+    - Simplify user experience
+    - Allow off-chain calculations to be performed in the relayer, reducing gas costs.
+    - Generally easy to develop
+
+However, they also have a couple notable downsides
+
+    - Adds a backend relaying component which is responsible for liveness
+    - Complicates fee-modeling, as relayers are responsible for paying target chain fees.
+
+Because relayers are responsible for liveness, they become another dependency component for the xDapp. If the relayers are all down, your application has an outage, similarly to how other dependencies such as the frontend, blockchain nodes, blockchains, third party APIs, etc, also can cause outages.
+
+To mitigate this, many relayers can be run in order to provide redundancy. It's also possible to design specialized relaying solutions which are entirely decentralized, such that there are a network of relayers which run based off economic incentives. However, creating a robust model for decentralized relaying is generally application-specific and somewhat complex.
+
+Due to specialized relayers being such a common solution,there is a reference implementation provided in the main Wormhole repository, which stands up the infrastructure needed to provide both a Spy and REST interface, and to interact with each blockchain in the ecosystem. If you plan to develop a specialized relayer, consider starting from the reference implementation, and add modifications as needed.
+
+# Generic Relayers
+
+_Note: this feature is not yet available in mainnet_
+
+Because relaying is such an integral component to xDapps, Wormhole has built a protocol which allows developers to utilize a decentralized network of untrusted relayers to deliver their messages, removing the specialized relayer as an infrastructure responsibility.
+
+In order to utilize the generic relayer network, developers must request delivery from the Wormhole Relay Ecosystem Contract, and must also implement a "receiveRelay" function in their contracts, which will be called by the relayer. Once a delivery has been requested, the VAA is guaranteed to be delivered within a certain timeframe. The specifics of this vary by blockchain and smart contract runtime.
+
+Generic relayers have the following benefits:
+
+    - Simplified UX
+    - No relayer infrastructure requirements for the developer
+
+Along with the following potential downsides:
+
+    - Require all calculations to be done on-chain
+    - Less gas efficiency
+    - May not be supported on all chains
+
+---
+
+That's the main overview of how xData is emitted, verified, and delivered across the Wormhole ecosystem. In the next section we'll discuss the Portal Ecosystem contracts, which allow xAssets to be created and moved freely around the ecosystem.

src/wormhole/7_portalTokenBridge.md

@@ -0,0 +1,53 @@
+# Portal
+
+Portal is a set of ecosystem contracts which provision Wormhole's xAsset layer. These contracts allow tokens to be bridged around the Wormhole Ecosystem in a **path-independent** fashion, and in a manner easily composeable with other functions in the Wormhole ecosystem, such as Core-Layer messaging.
+
+The Portal functions are a major focus of the [Wormhole Typescript SDK](https://www.npmjs.com/package/@certusone/wormhole-sdk). If you're looking to interact with Portal directly from a typescript client or backend, you should start there. This section will only provide a high-level overview of how to interact with the Portal contracts. If you'd prefer to look at code examples, they are provided in the **Portal Examples** section.
+
+## Creating xAssets
+
+xAssets always have an **origin chain**. This is the chain where the token is initially minted, via the standard of that chain (ERC-20, SPL, etc).
+
+To begin converting this asset into an xAsset, an **attestation** must first be created. This is accomplished by simply calling the **attest** function on the Portal contract of the origin chain.
+
+    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 eachother. This means the wrapped token from any chain can be exchanged for the original token or any of the wrapped tokens from other chains.
+
+## Transferring Assets
+
+    function transferTokens(
+        address token,
+        uint256 amount,
+        uint16 recipientChain,
+        bytes32 recipient,
+        uint256 arbiterFee,
+        uint32 nonce) returns (uint64 sequence)
+
+Initiating a token transfer is a relatively straightforward affair. After the transfer is initiated, the Guardians will produce a transfer VAA once finality has been reached on the **source chain**. The VAA must then be relayed to the **target chain**.
+
+All tokens managed by Portal are backed by the origin asset, and this allows for the tokens to be transferred in a path-independent fashion. Regardless of what chain the tokens are passed to, a 'double-wrapped' asset will never be created for a single backing asset. Additionally, because Portal is based purely on a wrapping model, there are no liquidity limitations.
+
+## Contract-Controlled Transfers
+
+Contract Controlled Transfers (CCTs) are a feature designed to allow xDapp contracts to easily perform Portal transfers. Contract controlled transfers are quite similar to simple transfers, but have two additional features:
+
+- An arbitrary byte array can be appended to the transfer, which can be used to easily pass additional information to the recipient contract.
+- The CCT VAA redeem can only be performed by the recipient contract, as opposed to basic transfers, which can be performed by any caller. This ensures that any additional operations which the contract wants to perform as part of the redeem transaction must be executed.
+
+In short, basic transfers are intended to transfer tokens from one wallet to another, whereas CCTs are meant to transfer tokens from one smart contract to another. If you're writing an xDapp, you probably want to use CCTs for the most part.
+
+In the next section. We'll discuss Wormchain, and some of the upcoming features it will enable.

src/wormhole/8_wormchain.md

@@ -0,0 +1,12 @@
+# Wormchain
+
+Wormchain is a purpose-built cosmos blockchain for the Wormhole ecosystem. It has two primary functions:
+
+1. Provide a public and auditable mechanism for users to interact with the Guardian Network.
+2. Create a robust platform for on-chain infrastructure which would be infeasible to build elsewhere.
+
+Wormchain is less relevant to xDapp developers than some other parts of the ecosystem, but it will become an increasingly important component as Wormhole matures and more features are added. Wormchain is built to provide things like:
+
+    - Redundant security checks
+    - Governance
+    - Interactions with 'legacy' chains like Bitcoin

src/wormhole/wormholeOverview.md

@@ -1,26 +0,0 @@
-# What is Wormhole?
-
-Wormhole is a generic message passing protocol that connects to multiple chains including Ethereum, Solana, Terra, Binance Smart Chain, Polygon, Avalanche, Oasis, and Fantom.
-Wormhole does this through emitting messages from one chain which are observed by a Guardian network of nodes and verified. After verification, this message is submitted to the target chain for processing.
-This simple message passing primitive enables cross chain functionality. Users interact with xDapps (cross chain decentralized applications) to transfer xAssets (cross chain assets) between networks or access their xData (cross chain data) to provide them services on their current network.
-On top of the Wormhole message protocol, there’s two specific applications that help concentrate liquidity for xAssets. The Portal Token Bridge and Portal NFT Bridge provide a standard message format for token and NFT transfers across the Wormhole bridge.
-
-## What can Wormhole be used for?
-Wormhole can be used by developers to build xDapps, a new type of chain agnostic application that can take advantage of xAssets and xData. This allows for access to increased liquidity, communities, and user identity.
-
-Some prominent examples of xDapps:
-
-- Cross chain exchange:
-
-    Using Portal, the Token Bridge built on Wormhole, a developer can build an exchange that allows deposits from any Wormhole connected chain, massively increasing the liquidity their users can interact with. A user could directly deposit LUNA from Terra into an app running on Solana! All the developer has to do is integrate Wormhole SDK into their frontend and that deposit will get picked up by the Portal Token Bridge, and taken over to target chain.
-
-- Cross chain governance app:
-
-    Consider all the NFT collections on various networks. If a group of these collections on different networks wanted their holders to vote on a combined proposal, they could pick a “Voting” chain, and use Wormhole to shuttle all the votes from cast on their various chains to the voting chain.
-
-- Cross chain game: 
-
-    A game could be built and played on a performant network like Solana, and it’s rewards issued as NFTs on a different network, for example Ethereum.
-
-## How does Wormhole work?
-Wormhole has a Core Bridge contract deployed on all the connected networks. Wormhole Guardians run a full node for each of the connected chains, specifically listening to any events from the Core Contracts. The core contracts emit a message, which is picked up by the Guardians. The Guardians verify the message and sign it, creating a VAA (Verified Action Approval). This VAA then sits on the Guardians network where it can be retrieved by the user or by a relayer to be submitted to the target chain to process the message. Unlike other bridges, a relayer in Wormhole has no special privileges, it’s just a piece of software that shuttles messages between the Guardian network to the target chain, and is not a trusted entity.