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

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

This commit is contained in:
spacemandev 2022-09-02 01:02:14 -05:00
parent 5c818f055c a68d1e07ef
commit 72757e1b3b
4 changed files with 23 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/dapps/architecture/0_dappDesign.md
View File

@ -1,5 +1,5 @@
# xDapp Design
Now that we've established the concepts and major components underlying xDapps, let's dive into the process of designing one. This chapter will help guide you through the considerations you should make before developing an xDapp, including topics like network topology, protocol design, and more.
Now that we've established the major concepts and components underlying xDapps, let's dive into the process of designing one. This chapter will guide you through the considerations you should make before developing an xDapp, including topics like network topology, protocol design and more.
By the end of this chapter, you should have all the tools you need to lay out a design for your xDapp and start building.
By the end of this chapter, you will have all the tools you need to lay out a design for your xDapp and start building.

10
src/dapps/architecture/1_keyConsiderations.md
View File

@ -1,19 +1,19 @@
# Key Considerations
Before we get started, we should outline the key considerations which will shape your xDapp. Over the course of the chapter, we'll elaborate on how decisions made about these key items impact the way you may want to structure your application as a whole.
Before we get started, we should outline the key considerations that will shape your xDapp. Below, we'll show how each of the decisions you make about these key considerations can impact the structure of your application as a whole.
### Why?
Why you are building an xDapp is definitely the foremost consideration. In the first chapter, we went over the [advantages](../5_advantages.md) of cross-chain development. Which of these advantages are most important to you? Are you building a brand new application and you want the widest reach? Are you trying to increase the performance of an existing Dapp? Are you interested in composing on top of protocols which only exist in certain ecosystems? Deciding what your key priorities are will help you make the correct technical decisions and tradeoffs when designing your xDapp.
The reason you're building an xDapp is the foremost consideration. Think about the [advantages](../5_advantages.md) of cross-chain development -- which of these are most important to you? Are you building a brand new application and you want the widest reach? Are you trying to increase the performance of an existing Dapp? Are you interested in composing on top of protocols that only exist in certain ecosystems? Determining your key priorities will help you make better technical decisions and tradeoffs when designing your xDapp.
### Target Ecosystems & Languages
Which blockchains do you intend to support? Due to the fact that blockchains utilize different virtual machines, supporting more blockchains often (but not always) requires writing smart contracts in more than one language.
Which blockchains do you intend to support? Because different blockchains utilize different virtual machines, supporting more blockchains often requires writing smart contracts in more than one language.
### Data Flows
Where does your data originate from and where does it have to go? Does all your data come from user-initiated transactions? Do you have governance messages which need to be emitted from a central governance contract? Do you have automated actions which need to happen periodically to synchronize your data?
Think about where your data originates and where it needs to go. Does all your data come from user-initiated transactions? Do you have governance messages that need to be emitted from a central governance contract? Do you have automated actions which need to happen periodically to synchronize your data?
### Liquidity & Tokens
Not all xDapps deal with tokens, but certainly quite a few do. If your app is centered around tokens, you'll have to decide what tokens will be utilized, where liquidity is aggregated (or fractured), and how this liquidity can be best utilized across your application.
Not all xDapps deal with tokens, but many do. If your app is centered around tokens, you'll have to decide which tokens will be utilized, where liquidity is aggregated (or fractured), and how this liquidity can be best utilized across your application.

8
src/dapps/architecture/2_ecosystems.md
View File

@ -4,7 +4,7 @@ At present, there are 3 ecosystems supported by Wormhole, though the number of s
### EVM
EVM is the most popular ecosystem, and most xDapps will have some support for this platform. These contracts are written in Solidity, and it is generally a 'jack of all trades' style of computation environment. A common strategy for xDapps is to develop one single contract in Solidity, and then deploy that contract to all the supported EVM blockchains.
EVM is the most popular ecosystem, and most xDapps will have some support for this platform. These contracts are written in Solidity -- a 'jack of all trades' style of computation environment. A common strategy for xDapps is to develop one single contract in Solidity, and then deploy that contract to all the supported EVM blockchains.
Example chains:
@ -21,12 +21,12 @@ Example chains:
### Solana
Solana is characterized by its high transaction throughput, increased computation power, and cheap data storage when compared to EVM environments. These contracts are written in Rust.
Solana is characterized by its high transaction throughput, increased computation power and cheap data storage when compared to EVM environments. These contracts are written in Rust.
### Cosmos
Cosmos is a network of blockchains which share a common ecosystem. Cosmos is a general purpose environment, but excels in certain areas such as application-specific blockchains, and having Cosmos-wide standards via its sdk 'modules'. It uses CosmWasm for its smart contract runtime, which is based in Rust.
Cosmos is a network of blockchains that share a common ecosystem. Cosmos is a general purpose environment, but excels in certain areas like application-specific blockchains and the use of Cosmos-wide standards via its sdk 'modules.' It uses CosmWasm for its smart contract runtime, which is based in Rust.
### Read-Only Chains
Some chains in the Wormhole ecosystem are 'Read-Only'. These chains are able to verify messages which are emitted from other chains in the network, but are not able to emit messages themselves. For information about these chains, check the [contracts page](../../reference/contracts.md).
Some chains in the Wormhole ecosystem are 'Read-Only.' These chains are able to verify messages emitted from other chains in the network, but are not able to emit messages themselves. For information about these chains, check the [contracts page](../../reference/contracts.md).

22
src/dapps/architecture/3_protocolDesign.md
View File

@ -1,16 +1,18 @@
# Protocol Design
Wormhole's key feature is that it brings message passing to the world of blockchain. As such, it's worthwhile to take some inspiration from other areas of software development which are based on similar principles.
They key feature of Wormhole is bringing message passing to the world of blockchain, so it's worthwhile to take some inspiration from other areas of software development that are based on similar principles.
Much of the traditional web stack is based on distributed systems, which rely on message passing to create well-defined interfaces and boundaries for disparate systems to work together. We should similarly think of xDapps as web3 distributed systems founded upon similar paradigms.
Much of the traditional web stack is based on distributed systems that rely on message passing to create interfaces and boundaries for disparate systems to work together. We can think of xDapps as web3 distributed systems founded on similar paradigms.
## Protocol First Design
Protocol first design is a design philosophy where you first lay out your data types, message formats, and supported operations into a well-defined protocol. This creates a solid protocol layer which can serve as the foundation for your application, and the code instantiating that protocol can be treated as an implementation detail when reasoning about the protocol itself.
Protocol first design is a design philosophy where you initially lay out your data types, message formats and supported operations into a well-defined protocol. This creates a solid protocol layer which can serve as the foundation for your application. This way, the code instantiating that protocol can be treated as an implementation detail when reasoning about the protocol itself.
At this stage in the design, you should also consider the incentive structures surrounding your protocol. What is the incentive for each party to engage? Are there economic attack vectors in your application which might jeopardize its security? Do certain market conditions result in perverse outcomes? This stage of the process could be as simple as stating "people will want my NFT", or as difficult as designing an entire ecosystem with multiple competing interested parties. It depends on what your goals are.
At this stage in the design, you should also consider the incentive structures surrounding your protocol. What is the incentive for each party to engage? Are there economic attack vectors in your application which might jeopardize its security? Do certain market conditions result in perverse outcomes?
Once you have a clear idea of your core product, incentives, and users, you can begin to lay out your data model, and from there define your message types and operations.
Depending on your goals, this stage of the process can be as simple as stating "people will want my NFT" or as difficult as designing an entire ecosystem with multiple competing interested parties.
Once you have a clear idea of your core product, incentives and users, you can begin to lay out your data model. From there, you can define your message types and operations.
## Common Strategies and Conventions
@ -18,14 +20,14 @@ Once you have a clear idea of your core product, incentives, and users, you can
Because there are many different formats for addresses across the different supported blockchains, a compatibility format is necessary. Wormhole uses its own address format (generally referred to as Wormhole format) in order to solve this issue. These addresses correspond 1 to 1 with native addresses on each chain.
A Wormhole address is a tuple containing the 2 byte Wormhole chain ID, and also a 32 byte shim address. The Wormhole address format is therefore 34 bytes.
A Wormhole address is a tuple containing the 2 byte Wormhole chain ID and a 32 byte shim address, totalling 34 bytes.
For example, because EVM addresses are only 20 bytes in length, to convert this to a Wormhole address, the address is left-padded with zeros until it's length 32. To transmit as this as a single item, the Wormhole chain ID is usually appended to the front, resulting in a 34 byte address.
Because EVM addresses are only 20 bytes in length, to convert this to a Wormhole address, the address is left-padded with zeros until it's length 32. To transmit as this as a single item, the Wormhole chain ID is usually appended to the front, resulting in a 34 byte address.
When dealing with addresses inside your messages, it's recommended to always convert to Wormhole format and transmit in that format. You will regularly encounter addresses in this format when interacting with other parts of the Wormhole ecosystem, and adopting this format in your protocol will enhance your forward compatibility as you add more chains.
When dealing with addresses inside your messages, it's recommended to always convert to Wormhole format and transmit in that format. You will regularly encounter addresses in the Wormhole format when interacting with other parts of the ecosystem, and adopting the format in your protocol will enhance your forward compatibility as you add more chains.
### Trusted Contract Network
If your protocol has smart contracts deployed to multipe chains, it will be important for your contracts to know which other contracts are 'in network' for your protocol, as commonly the first check performed when receiving a message is to validate that it originates from a trusted source.
Typically, the first check performed when receiving a message is to validate that it originates from a trusted source. If your protocol has smart contracts deployed to multipe chains, it will be important for your contracts to know which other contracts are 'in network' for your protocol.
Generally, this list of trusted contracts is stored in the state of each contract individually, and updating the trusted contracts is tied into the governance mechanism of the protocol.
Generally, this list of trusted contracts is stored in the state of each contract individually. Updating the trusted contracts is tied into the governance mechanism of the protocol.