Wormhole: line edits

src/wormhole/1_whatIsWormhole.md

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

src/wormhole/2_architectureOverview.md

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

src/wormhole/3_coreLayerContracts.md

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

src/wormhole/4_vaa.md

@@ -27,7 +27,7 @@ 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
 

src/wormhole/5_guardianNetwork.md

@@ -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.
 
@@ -18,29 +24,25 @@ 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.
 

src/wormhole/7_TokenBridge.md

@@ -1,8 +1,10 @@
-# Portal xAsset Bridge
+# 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.
+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 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. 
+This section provides a high-level overview of how to interact with the xAsset contracts. 
+
+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
 
@@ -39,15 +41,17 @@ These assets are all **fungible** with each other. This means the Wormhole-wrapp
 
 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.
+All tokens managed by the Token Bridge 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:
+CCTs allow xDapp contracts to easily perform simple Token Bridge 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.

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.