revised summary, intro, dapp basics, and cross-chain history

src/SUMMARY.md

@@ -1,66 +1,125 @@
 # Summary
 
-- [Introduction](./introduction/introduction.md)
-    - [What is an xDapp](./introduction/xdapp.md)
-    - [What is Wormhole](./introduction/wormhole.md)
-    - [What is Portal]()
-- [Wormhole Architecture]()
-    - [Core Bridge Contracts]()
-    - [VAA: Verifiable Action Approval]()
-    - [Guardian]()
-    - [Relayers]()
-- [Tools]()
-    - [Testnet]()
-    - [Wormhole Explorer]()
-    - [Bridge UI]()
-    - [Tilt]()
-    - [Wormhole SDK]()
-- [Portal JS Client Transfers]()
-    - [Examples]()
-        - [EVM to Solana Transfer]()
-        - [Polygon to Oasis with Relayers]()
-    - [Portal Payloads]()
-- [xDapp Development]()
-    - [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)
-        - [EVM]()
-            - [Foundry]()
-        - [Solana]()
-            - [Solana CLI]()
-            - [Anchor]()
-        - [Algorand]()
-    - [Sending Messages](./development/messages/sending/overview.md)
-        - [EVM](./development/messages/sending/evm.md)
-        - [Solana]()
-        - [Algorand]()
-    - [Registering xDapps](./development/messages/registration/overview.md)
-        - [EVM](./development/messages/registration/evm.md)
-        - [Solana]()
-        - [Algorand]()
-    - [Relaying Messages](./development/messages/relaying/overview.md)
-        - [Manual Relays]()
-        - [Rest Relayers]()
-        - [Generic Relayers]()
-        - [Spy Relayer]()
-    - [Receving Messages]()
-        - [EVM]()
-        - [Solana]()
-        - [Algorand]()
-- [Portal xDapps]()
-    - [Payload 1 Transfers]()
-    - [Payload 2 Attestations]()
-    - [Payload 3 Contract Controlled Transfers]()
-- [Projects](./projects/summary.md)
-    - [Messenger](./projects/messenger/introduction.md)
-        - [Prerequistes]()
-            - [EVM]()
-    - [Lever Puzzle]()
----
-- [Wormhole Reference]()
-    - [Contracts]()
-    - [Tilt Accounts]()
-    - [RPC Nodes]()
+[Introduction](./introduction/introduction.md)
 
+---
+
+# Overview
+
+- [xDapps](./dapps/xdappOverview.md)
+
+  - [De-fi Ecosystem Basics](./dapps/defiBasics.md)
+  - [Cross-Chain Interoperability](./dapps/crossChainInteroperability.md)
+  - [xData & xAssets](./dapps/xdataxassets.md)
+  - [What is an xDapp?](./dapps/whatIsanXdapp.md)
+  - [Advantages](./dapps/advantages.ms)
+
+- [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 Token Bridge & xAssets](./wormhole/portalTokenBridge.md)
+  - [Wormchain](./wormhole/wormchain.md)
+
+---
+
+# xDapp Architecture
+
+- [xDapp Design]()
+  - [Key Considerations]()
+  - [Ecosystems]()
+    - [EVM]()
+    - [Solana]()
+    - [Cosmos]()
+    - [Algorand]()
+  - [Protocol-First Design]()
+  - [Topology]()
+    - [Hub & Spoke]()
+    - [Mesh]()
+  - [xAssets]()
+  - [Relayers]()
+    - [Generic Relayers]()
+    - [Protocol-Specific Relayers]()
+  - [Security]()
+    - [Trust Assumptions]()
+    - [Layer 1 Risk]()
+    - [Finality Guarantees]()
+  - [Examples]()
+    - [Cross-Chain Swap]()
+    - [Remote Staking]()
+  - [Common Use Cases]()
+  - [FAQ]()
+
+---
+
+# xDapp Development
+
+- [Before You Start]()
+  - [Choosing an Environment]()
+- [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)
+  - [EVM]()
+    - [Foundry]()
+  - [Solana]()
+    - [Solana CLI]()
+    - [Anchor]()
+  - [Algorand]()
+- [Sending Messages](./development/messages/sending/overview.md)
+  - [EVM](./development/messages/sending/evm.md)
+  - [Solana]()
+  - [Algorand]()
+- [Registering xDapps](./development/messages/registration/overview.md)
+  - [EVM](./development/messages/registration/evm.md)
+  - [Solana]()
+  - [Algorand]()
+- [Relaying Messages](./development/messages/relaying/overview.md)
+  - [Manual Relays]()
+  - [Rest Relayers]()
+  - [Spy Relayer]()
+  - [Generic Relayers]()
+- [Receving Messages]()
+  - [EVM]()
+  - [Solana]()
+  - [Algorand]()
+- [Projects](./projects/summary.md)
+  - [Messenger](./projects/messenger/introduction.md)
+    - [Prerequistes]()
+      - [EVM]()
+  - [Lever Puzzle]()
+- [Tools]()
+  - [Testnet]()
+  - [Wormhole Explorer]()
+  - [Bridge UI]()
+  - [Tilt]()
+  - [Wormhole SDK]()
+
+---
+
+# Portal Token Bridge
+
+- [Portal]()
+  - [Portal JS Client Transfers]()
+  - [Payload 1 Transfers]()
+  - [Payload 2 Attestations]()
+  - [Payload 3 Contract Controlled Transfers]()
+  - [Examples]()
+    - [EVM to Solana Transfer]()
+    - [Polygon to Oasis with Relayers]()
+  - [Portal Payloads]()
+
+---
+
+# Other Resources
+
+- [Glossary]()
+- [Reference]()
+  - [Github & Useful Links]()
+  - [Contracts]()
+  - [Tilt Accounts]()
+  - [RPC Nodes]()

src/dapps/advantages.md

@@ -0,0 +1,6 @@
+unified liquidity
+larger user base
+increased performance
+lower transaction fees
+future proofing
+retains decentralization

src/dapps/advantages.ms

@@ -0,0 +1 @@
+# Advantages

src/dapps/crossChainInteroperability.md

@@ -0,0 +1,31 @@
+# Cross-Chain Interoperability
+
+The fact that each cryptocurrency is locked to its own chain has been a limitation of blockchain technology since day one. It's not 'real' Bitcoin unless it's on the Bitcoin ledger, and it's not 'your' Bitcoin unless you have the private keys to the wallet.
+
+This restriction is fine if you're content with just sending Bitcoin around, but it becomes a major obstacle as soon you want to exchange Bitcoin for any other currency.
+
+The first attempt at solving this problem was by creating cryptocurrency exchanges, such as Coinbase and Binance. Today these are refered to as centralized exchanges, or CEXs.
+
+Centralized Exchanges play an important role in the cryptocurrency space, but they are certainly not a silver bullet for cross-chain interoperability. This is primarily due to two reasons.
+
+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 is order to obtain a token which is not native to the blockchain, 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 bridge's 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.
+- 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 then bridges become necessary infrastructure. Each solution 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.
+
+The way to address these issues is not to slap another bandage on top, but rather to go back to the drawing board, and design new primatives and core infrastructure which will allow the next generation of decentralized applications to never suffer from these problems in the first place.
+
+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 can be labeled as **xData**.

src/dapps/defiBasics.md

@@ -0,0 +1,24 @@
+# Dapp Basics
+
+The fundamental starting point for any decentralized computing discussion is, of course, the blockchain.
+
+Since the launch of Bitcoin in 2009, the cryptocurrency and decentralized computing ecosystem has evolved and expanded year-over-year, to the point where it now includes hundreds of blockchains, often also referred to as **Layer 1s**.
+
+Somewhat newer, however, is the concept of a **Decentralized Application** or **Dapp**, which only came into being in 2015 with the launch of Ethereum and 'smart contracts'. Prior to the introduction of smart contracts, blockchain transactions were limited in their capacities, and could more-or-less only transfer funds from point A to B. Smart contracts allow developers to perform arbitrary on-chain computation as part of a blockchain transaction. This feature opened the door for blockchain technology to become a global general-purpose computing platform, rather than just a simple ledger of money transfers.
+
+In the introvening years, a rich ecosystem of Dapps has cropped up across the myriad of smart-contract-enabled blockchains. These Dapps provide a wide array of services, and in some cases have created entirely new products. Dapps fall into categories such as:
+
+- Decentralized Exchanges (DEXs)
+- Decentralized Autonomous Organizations (DAOs)
+- Borrow-Lend Platforms
+- Decentralized Games
+- NFT Protocols
+- and more
+
+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.
+
+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.
+
+In the next section, we'll discuss the challenges associated with cross-chain interoperability, and introduce a few key concepts from Wormhole which act as data primitives for this new and growing cross-chain ecosystem.

src/dapps/whatIsanXdapp.md

@@ -0,0 +1,9 @@
+# What is an xDapp
+
+xDapps are _cross chain decentralized applications_. In short, unlike traditional blockchain programs which are tied to a specific chain, xDapps take advantage of _bridges_ like Wormhole to be able to interact with applications from other networks.
+
+extension of Dapps.
+Key component is that they support multiple chains.
+Usually means deploying contracts to each chain,
+Can provide unique user experiences which aren't accomplishable via traditional dapps
+Oracles, gaming, de-fi, etc leverage the strengths of blockchains

src/dapps/xdappOverview.md

@@ -0,0 +1,3 @@
+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/xdataxassets.md

@@ -0,0 +1,3 @@
+xData is characterized by its ability to be accessed across the entire ecosystem
+Assets are a special form of data
+Key aspects of xData and thus xAssets are that they are accessible across the entire ecosystem. xAssets are meant to be fungible and path-independent. Abstracting away what chain is custodying or processing these assets.

src/introduction/introduction.md

@@ -1,11 +1,19 @@
 # Introduction
 
-Welcome to the xDapp Book and beginning your journey to be a cross-chain developer. As crypto ecosystems mature, more and more applications will need to interact with programs outside the infrastructure they are deployed on. In Web2 we see this every day, as infrastructure like Azure, GCP, and AWS is abstracted away from the everyday user and applications can freely talk to each other over HTTP.
+## Welcome to the Wormhole xDapp Book!
 
-For blockchain applications to unlock their true potential, they too must be able to talk to applications on various infrastructure using a common language. These cross chain applications (xDapps) give rise to cross chain data (xData) and cross chain assets (xAssets). With these powerful primitives, blockchain applications can deliver on their promise of interoperability and composability.  
+This guide aims to help you in your journey as a cross-chain developer by explaining the core concepts of Wormhole and xDapp development.
 
-Ready to step *into the wormhole*?
+We'll start off by outlining the most important aspects of Wormhole, and the considerations which must be taken when developing an xDapp. After that, the second portion of the book helps you set up a development environment and get started writing actual code.
+
+By the end of this guide, you should be ready to build and deploy your first xDapp!
+
+While this document doesn't assume you have experience with any particular technologies, a general understanding of blockchain development will help you get up to speed.
+
+Ready to step _into the wormhole_?
 
 ---
-Check out the [github repository](https://www.github.com/certusone/xdapp-book) of these docs to find the accompanying code in the projects/ directory.
 
+Check out this project's [github repository](https://www.github.com/certusone/xdapp-book) to find the accompanying code examples.
+
+See the **Reference** section for additional resources as well.

src/introduction/xdapp.md

@@ -1,3 +0,0 @@
-# What is an xDapp
-
-xDapps are *cross chain decentralized applications*. In short, unlike traditional blockchain programs which are tied to a specific chain, xDapps take advantage of *bridges* like Wormhole to be able to interact with applications from other networks.