wormhole: formatting changes

src/wormhole/5_guardianNetwork.md

@@ -36,7 +36,7 @@ With our perspective on Decentralization laid out, the remaining elements fall i
 
 ## Modularity
 
-The Guardian Network is robust and trustworthy by itself, so there'ss no need for components like the relayer to contribute to the security model. That makes Wormhole able to have simple components that are very good at the one thing they do. That way, Guardians only need to verify on-chain activity and produce VAAs while Relayers only need to interact with blockchains and deliver messages.
+The Guardian Network is robust and trustworthy by itself, so there's no need for components like the relayer to contribute to the security model. That makes Wormhole able to have simple components that are very good at the one thing they do -- Guardians only need to verify on-chain activity and produce VAAs; Relayers only need to interact with blockchains and deliver messages.
 
 The signing scheme of the VAAs can be changed without affecting downstream users, and multiple relay mechanisms can exist independently. xAssets can be implemented purely at the application layer and xDapps can utilize whatever components suit them.
 
@@ -44,7 +44,7 @@ The signing scheme of the VAAs can be changed without affecting downstream users
 
 Today, Wormhole supports a wider range of ecosystems than any other interoperability protocol because it uses simple tech (t-schnorr signatures), an adaptable, heterogenous relayer model, and a robust validator network.
 
-Wormhole can expand to new ecosystems as quickly as a Core Contract can be developed for the smart contract runtime. Relayers don't need to be factored into the security model--they just need to be able to upload messages to the blockchain. The Guardians are able to observe every transaction on every chain, without taking shortcuts.
+Wormhole can expand to new ecosystems as quickly as a Core Contract can be developed for the smart contract runtime, Guardians can set up infrastructure to observe every transaction for that blockchain, and Relayers can upload messages to that blockchain.
 
 ## Scalability
 
@@ -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.

src/wormhole/6_relayers.md

@@ -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.
 
@@ -12,29 +18,25 @@ In Wormhole, relayers are neither trusted nor privileged. This means relayers **
 
 From this perspective, relayers are just delivery trucks that deliver VAAs to their destination, and have no capacity to tamper with the delivery outcome. VAAs either get delivered or don't, which makes relayers analagous to the off-chain 'crank turners' of traditional Dapps.
 
-As a result, Wormhole is able to facilitate a variety of heterogenous relaying mechanisms, and the developer is able to choose whatever best suit their needs.
+As a result, Wormhole is able to facilitate a variety of heterogenous relaying mechanisms, and the developer is able to choose the option that best suits their needs.
 
 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
 
@@ -42,7 +44,7 @@ Specialized relayers solve the UX problems of client-side relayers by adding a b
 
 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 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,19 +57,21 @@ 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, [here](https://github.com/wormhole-foundation/wormhole/tree/feat/plugin_relayer/relayer/plugin_relayer) 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.
 
-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.
+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.
 
-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.
+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
 
 _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.
+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 from development teams.
 
-In order to utilize the generic relayer network, developers must request delivery from the Wormhole Relay Ecosystem Contract and must also implement a "receiveRelay" function in their contracts, which will be called by the relayer. Once a delivery has been requested, the VAA is guaranteed to be delivered within a certain timeframe. The specifics of this vary by blockchain and smart contract runtime.
+In order to utilize the generic relayer network, developers must request delivery from the Wormhole Relay Ecosystem Contract and must also implement a `receiveRelay` function in their contracts, which will be called by the relayer. Once a delivery has been requested, the VAA is guaranteed to be delivered within a certain timeframe. The specifics of this vary by blockchain and smart contract runtime.
 
 Generic relayers have the following benefits:
 
@@ -80,6 +84,8 @@ And potential downsides:
     - They have less gas efficiency
     - They may not be supported on all chains
 
+Overall, Generic Relayers simply both the developer and user experience. It's generally recommend if your goal is a highly-polished user experience and increase decentralization of the xDapp.
+
 ---
 
 In the next section, we'll discuss the Portal Ecosystem contracts that allow xAssets to be created and moved freely around the ecosystem.

src/wormhole/8_wormchain.md

@@ -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.