From e9be34f4e1fa11e92b2728a45eab2261bb46cb1b Mon Sep 17 00:00:00 2001 From: chase-45 Date: Thu, 18 Aug 2022 14:14:02 -0400 Subject: [PATCH] line edits --- src/dapps/architecture/0_dappDesign.md | 2 +- src/dapps/architecture/1_keyConsiderations.md | 6 ++--- src/dapps/architecture/2_ecosystems.md | 4 ++-- src/dapps/architecture/3_protocolDesign.md | 16 ++++++------- src/dapps/architecture/4_topology.md | 24 +++++++++++-------- src/dapps/architecture/5_relayers.md | 16 ++++++++----- 6 files changed, 38 insertions(+), 30 deletions(-) diff --git a/src/dapps/architecture/0_dappDesign.md b/src/dapps/architecture/0_dappDesign.md index c5d1b73..934e9a1 100644 --- a/src/dapps/architecture/0_dappDesign.md +++ b/src/dapps/architecture/0_dappDesign.md @@ -1,5 +1,5 @@ # xDapp Design -Now that we've established the concepts underlying xDapps and the major components, let's dive into the design process surrounding xDapps. This chapter will help guide you through the considerations you should make before developing an xDapp, including topics like security, network topology, protocol design and more. +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. 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. diff --git a/src/dapps/architecture/1_keyConsiderations.md b/src/dapps/architecture/1_keyConsiderations.md index 7a14cea..7f5090e 100644 --- a/src/dapps/architecture/1_keyConsiderations.md +++ b/src/dapps/architecture/1_keyConsiderations.md @@ -1,6 +1,6 @@ # 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 points impact the way you may want to structure your application as a whole. +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. ### Why? @@ -8,11 +8,11 @@ Why you are building an xDapp is definitely the foremost consideration. In the f ### Target Ecosystems & Languages -A major consideration is which blockchains you intend to support. Because 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? 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. ### 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 location? Do you have automated actions which need to happen periodically to synchronize your data? +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? ### Liquidity & Tokens diff --git a/src/dapps/architecture/2_ecosystems.md b/src/dapps/architecture/2_ecosystems.md index 8f73bce..1741cd7 100644 --- a/src/dapps/architecture/2_ecosystems.md +++ b/src/dapps/architecture/2_ecosystems.md @@ -1,10 +1,10 @@ # Ecosystems -At present, there are 3 ecosystems supported by Wormhole, though the number of ecosystems supported is always growing. +At present, there are 3 ecosystems supported by Wormhole, though the number of supported ecosystems is always growing. ### EVM -EVM is the most popular ecosystem, and most xDapps will have some support for this platform. These contracts are written in Solidity, and are generally a 'jack of all trades' type 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, 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. Example chains: diff --git a/src/dapps/architecture/3_protocolDesign.md b/src/dapps/architecture/3_protocolDesign.md index 0cc6864..0a16262 100644 --- a/src/dapps/architecture/3_protocolDesign.md +++ b/src/dapps/architecture/3_protocolDesign.md @@ -2,13 +2,13 @@ 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. -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 based on similar paradigms. +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. ## 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. -At this stage in the design, you should first 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 interests. 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? 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. 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. @@ -16,16 +16,16 @@ Once you have a clear idea of your core product, incentives, and users, you can ### Address Space -Because there are many different formats for addresses across the ecosystem, 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. +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 consists of a tuple containing the 2 byte Wormhole chain ID, and also a 32 byte shim address. The Wormhole address format is then 34 bytes. +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. -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. +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. -When dealing with addresses inside your messages, it's recommended to always convert to Wormhole format and transmit in that format. Primarily because you will regularly encounter these addresses when interacting with parts of the Wormhole ecosystem, but also because it will enhance your forward compatibility as you add more chains to your protocol. +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. ### Trusted Contract Network -If your application has smart contracts deployed to multipe chains, it will be important for your contracts to know which other contracts are 'in network' for your application, as commonly the first check performed when receiving a message is to validate that it originates from a trusted contract. +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. -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 application. +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. diff --git a/src/dapps/architecture/4_topology.md b/src/dapps/architecture/4_topology.md index ea186f0..d344f12 100644 --- a/src/dapps/architecture/4_topology.md +++ b/src/dapps/architecture/4_topology.md @@ -8,7 +8,9 @@ Topology describes how data flows through your application, and the responsibili Ultra-light Clients are often the best option when designing an MVP for your xDapp. The defining feature of an Ultra-light Client is that you are able to support users from every chain in the Wormhole ecosystem while **only having smart contracts on a single chain (!!!)**. -The way this works is by deploying a single _hub_ contract (or just using an existing Dapp). You then add an entrypoint which supports _contract controlled transfers_ from the Asset Layer to send tokens to your hub contract, along with instructions for what to do with the tokens. Once you've performed the necessary operation, you bridge the resultant tokens back to the wallet which originally sent the CCT. The only on-chain components is the relatively lightweight wrapper around the core Dapp logic. All other aspects of this topology are off-chain and untrusted. This pushes most of the development work out of smart contracts and into client-side typescript, without altering the trust assumptions of your application. +This works by deploying a single _hub_ contract (or just using an existing Dapp) onto the hub chain. You then add an entrypoint which supports _contract controlled transfers_ from the xAsset contracts on the hub chain. This allows your hub contract to receive both tokens **and instructions for what to do with them** from other chains in the Wormhole ecosystem. + +From there, the hub contract performs any necessary operations, and bridges any resultant tokens back to the wallet which iniated the contract controlled transfer. The only on-chain components are hub contract, and a relatively lightweight wrapper which allows the hub contract to send and receive tokens using the xAsset contracts. All other aspects of this topology are off-chain and untrusted. This pushes most of the development work out of smart contracts and into client-side typescript. This dramatically decreases smart contract risk, without altering the trust assumptions of your application. **_Advantages:_** @@ -24,16 +26,18 @@ The way this works is by deploying a single _hub_ contract (or just using an exi ## Hub and Spoke -Hub and Spoke models are somewhat of a natural evolution of the ultra-light client. There is still a hub contract which handles all transactions, but there is not also a contract deployed to the remote chain. +Hub and Spoke models are somewhat of a natural evolution of the ultra-light client. There is still a hub contract which handles all transactions, but there is now also a contract deployed to all the remote chains. Advantages: -- Remote contracts are lightweight and don't carry huge amounts of risk. -- Can perform trusted checks on the remote chain. (Such as validating wallet balance) +- Remote contracts are lightweight and don't carry large amounts of risk. +- Can perform trusted checks on the remote chain. (Such as validating wallet balance, or any other piece of blockchain state) Disadvantages: -- Latency (same as Ultra Lightweight Clients) - Transaction Fees: - Managing multiple contracts +- Latency (same as ultra-light clients) +- Transaction Fees +- Managing multiple contracts ## Mesh @@ -41,14 +45,14 @@ A Mesh topology is one where each chain implements the full logic for a process, Advantages: -- Latency: Users can perform their operation without waiting for other chains. +- Latency: Users can often perform their operation without waiting for other chains. - Transaction Fees: Does not stack the transaction fees of multiple chains. Disadvantages: - Complexity: there are now quite a few contracts to manage, especially if they are implemented multiple times across different VMs. -- Data desync: because each blockchain acts independently, each chain will have independent state. This can open up unwanted arbitrage opportunities and other discontinuities. -- Race conditions: In cases where an event is supposed to propage through the entire system at a fixed time (example: closing a governance vote), it will be difficult to synchronize all the blockchains. +- Data desync: because each blockchain acts independently, each chain will have independent state. This can open up unwanted arbitrage opportunities and other discrepancies. +- Race conditions: In cases where an event is supposed to propagate through the entire system at a fixed time (for example, when closing a governance vote), it can be difficult to synchronize all the blockchains. ## Distributed @@ -64,6 +68,6 @@ Disadvantages: ## Mix & Match -Different use cases have different optimal topologies, and it's possible to use different topologies for different workflows in your application. This means your should not feel 'locked in' to a single topology, and should instead consider designing each workflow independently. For example, Governance is generally best implemented using a Hub and Spoke topology, even if the rest of your application uses a Mesh architecture. As such, your contracts will likely evolve over time as your xDapp evolves and adds in additional workflows. +Different use cases have different optimal topologies, and it's possible to use different topologies for different workflows in your application. This means you should not feel 'locked in' to a single topology, and should instead consider designing each workflow independently. For example, governance workflows are generally best implemented using a Hub and Spoke topology, even if the rest of the application uses a Mesh architecture. As such, your contracts will likely evolve over time as your xDapp evolves and adds additional workflows. -You can also progress through different topologies. A common strategy is to start off with an ultra-light client, move to a hub and spoke configuration, and then add optimizations and specialties to your contracts as the need arises. +You can also progress through different topologies. A common strategy is to start off with an ultra-light client, move to a hub and spoke configuration, and then add optimizations and specialties to contracts as the need arises. diff --git a/src/dapps/architecture/5_relayers.md b/src/dapps/architecture/5_relayers.md index 99b5a99..10b06aa 100644 --- a/src/dapps/architecture/5_relayers.md +++ b/src/dapps/architecture/5_relayers.md @@ -1,12 +1,12 @@ # Relayers -In Chapter 2, we discussed the [general concepts associated with relayers in the Wormhole ecosystem](../../wormhole/6_relayers.md). In this section, the primary focus is to outline what considerations need to be taken into account when designing relayers in your application. +In Chapter 2, we discussed the [general concepts associated with relayers in the Wormhole ecosystem](../../wormhole/6_relayers.md). In this section, we'll elaborate on what considerations need to be taken into account when using relayers for your xDapp. ## Fundamentals The most important thing to remember about relayers is that they are _untrusted_. This means you don't have to trust them, but it also means you can't trust them. This is true of both generic and specialized relayers. -Let's dive into a little bit more detail about _why_ relayers are untrusted, and what this means for you when laying out a protocol. +Let's dive into a little more detail about _why_ relayers are untrusted, and what this means for you when designing a protocol. A few key properties of VAAs are that they: @@ -18,13 +18,15 @@ A few key properties of VAAs are that they: Relayers are untrusted as an inherent consequence of these properties. Anyone can pick up a VAA and deliver it anywhere they feel like, however, no one can alter the content of the VAA without invalidating the signatures. -So, when writing your contracts, it's incredibly important to only trust information _inside your contract_ or _inside of VAA content_. If you trust information provided by a relayer, you are opening yourself up to untrusted input attacks. +So, when writing your contracts, it's incredibly important to only trust information which is either **inside your contract** or **inside a VAA**. If you trust information provided by a relayer, you are opening yourself up to untrusted input attacks. The easiest and most secure way to interact with relayers then is to _only accept the VAA as input_. If the relayer can't provide any additional args, then there's no way for them to provide untrusted input. There are more advanced strategies whereby the relayer performs **untrusted** off-chain computation which is passed into the destination contract. These strategies can optimize gas costs, but must be used carefully, as they can create attack vectors if not used correctly. -Designing relayers is mostly a matter of structuring the messages in your protocol in a manner such that there is a single, deterministic way that they can be processed. Once you've designed your protocol, your relayers just need to be implemented correctly. Relayers are conceptually quite similar to "crank turner" processes used elsewhere in blockchain, in that there is only a single action which can be taken (pulling the crank), and their sole responsibility is to initiate this action and pay for the costs. +With this in mind, relayer design is mostly a matter of structuring the messages in your protocol in a manner such that there is a single, deterministic way that they can be processed. In a well designed protocol, relayers have a 'correct' implementation. + +Relayers are conceptually quite similar to "crank turner" processes used elsewhere in blockchain, in that there is only a single action which can be taken (pulling the crank), and their sole responsibility is to initiate this action and pay for the costs. --- @@ -34,7 +36,7 @@ Generic Relayers are a decentralized relayer network which can deliver arbitrary ### Advantages: -- Purely done on-chain. No need to host or maintain relayers +- Purely done on-chain. No need to develop, host, or maintain relayers ### Disadvantages: @@ -54,7 +56,7 @@ Specialized Relayers are relayers which are purpose-built to relay messages for ### Disadvantages -- Requires development work, and requires that someone continuously run these. +- Requires development work, and requires relayer hosting In the future, there may be ways to customize generic relayers such that they will gain the advantages of today's specialized relayers. @@ -67,3 +69,5 @@ There are tons of strategies here, and the 'best' strategy for an application is - pay the relayer with a potion of the tokens being sent cross-chain - collect a safe amount of gas money from the end user prior to performing any actions - 'lazy' relaying, where relaying might only become profitable in certain, potentially rare, market conditions + +Generic relayers have an incentive model built in to the network, so you do not need to design an incentive structure when using them.