|
1 | | -Design Document for Wormhole SDK |
2 | | ---------------------------------- |
3 | 1 |
|
4 | | -# Organization |
| 2 | +# Structure |
5 | 3 |
|
6 | | -Code is organized into workspaces so that each can be its own module. |
| 4 | +A primary goal for the SDK was to provide modular and specific access to the protocols build on Wormhole. |
7 | 5 |
|
8 | | -``` |
9 | | -core/ |
10 | | - base/ -- Constants |
11 | | - definitions/ -- VAA structures and module definitions |
12 | | - connect/ -- Primary package and interface through Wormhole |
13 | | -
|
14 | | -platforms/ -- Platform specific logic |
15 | | - evm/ |
16 | | - protocols/ |
17 | | - tokenBridge.ts |
18 | | - cctp.ts |
19 | | - chain.ts |
20 | | - platform.ts |
21 | | - ... |
22 | | - solana/ |
23 | | - protocols/ |
24 | | - tokenBridge.ts |
25 | | - chain.ts |
26 | | - platform.ts |
27 | | - ... |
28 | | - ... |
29 | | -``` |
30 | | - |
31 | | -# Concepts |
32 | | - |
33 | | -The `Wormhole` class provides methods to interact with the Wormhole protocol by mapping chain parameters to the `Platform` and `Chain` specific implementations. |
34 | | - |
35 | | -A `Platform` is a blockchain runtime, often shared across a number of chains (e.g. `Evm` platform for `Ethereum`, `Bsc`, `Polygon`, etc ...). |
36 | | - |
37 | | -A `Chain` is a specific blockchain, potentially with overrides for slight differences in the platform implementation. |
38 | | - |
39 | | -A `Protocol` (fka `Module`) is a specific application on a `Chain`, it provides a set of methods that can be called to accomplish some action (e.g. `TokenBridge` allows send/receive/lookup token, etc...) |
40 | | - |
41 | | -A `Signer` is an interface that provides a callback to sign one or more transaction objects. These signed transactions are sent to the blockchain to invoke some action. |
42 | | - |
43 | | -An `Attestation` is a signed guarantee that some _thing_ happened on a remote chain, sent to the target chain to complete a transfer. |
44 | | - |
45 | | - |
46 | | -# Details |
47 | | - |
48 | | -## Wormhole |
49 | | - |
50 | | -Registers Platforms |
51 | | - |
52 | | -Allows overriding chain specific configs (rpc, contract addresses, ...) |
53 | | - |
54 | | -Provides methods to get PlatformContext or ChainContext objects |
55 | | -```ts |
56 | | -wh.getPlatform("Evm") |
57 | | -wh.getChain("Ethereum") |
58 | | -``` |
59 | | - |
60 | | -Provides methods to create a `WormholeTransfer` for any `Protocol` |
61 | | -```ts |
62 | | -wh.tokenTransfer(...) |
63 | | -wh.nftTransfer(...) |
64 | | -wh.cctp(...) |
65 | | -//... |
66 | | -``` |
67 | | - |
68 | | -Provides methods to query an API for VAAs and token details |
69 | | -```ts |
70 | | -// grab a vaa with identifier |
71 | | -wh.getVaa(...) |
72 | | -// get the token details |
73 | | -wh.getOriginalToken(...) |
74 | | -wh.getWrappedToken(orig, chain) |
75 | | -``` |
76 | | - |
77 | | -## Platform |
78 | | - |
79 | | -Base class, implements Platform specific logic |
80 | | - |
81 | | -Parse Addresses |
82 | | - |
83 | | -Parse Message out of Transaction |
84 | | - |
85 | | -Sign/Send/Wait |
86 | | - |
87 | | -## ChainContext |
88 | | - |
89 | | -Defined in abstract ChainContext class |
90 | | - |
91 | | -Note: Dispatches many calls to the Platform, filling in details like ChainName and RPC |
92 | 6 |
|
93 | | -The `getRpc` method is the only platform specific thing _required_ to implement. |
| 7 | +To address this goal, the SDK is structured into layers |
94 | 8 |
|
95 | | -Responsible for holding RPC connection, initialized from default or overrides |
96 | | -```ts |
97 | | -cc.getRPC() // for evm -> ethers.Provider, for sol -> web3.Connection |
98 | 9 | ``` |
99 | | - |
100 | | -Holds references to Contract client |
101 | | - |
102 | | - |
103 | | -<!-- |
104 | | -Not Implemented |
105 | | -Provides methods to lookup details for contract addresses, finality, address parsers/formatters |
106 | | -
|
107 | | -```ts |
108 | | -cc.getTokenBridgeAddress() |
109 | | -cc.estimateFinality(txid) |
| 10 | +core/ -- Low level packages |
| 11 | + base/ -- Constants and utilities |
| 12 | + definitions/ -- Definitions of interfaces required for Platforms, Protocol interfaces and Payload layout structures |
| 13 | + icons/ -- Logos for chains |
| 14 | +
|
| 15 | +connect/ -- Makes use of the interfaces in `definitions` to expose protocols in a platform independent way. |
| 16 | +
|
| 17 | +platforms/ -- Contains `Platform` and `Protocol` implementations |
| 18 | + evm/ |
| 19 | + protocols/ -- Contains the Evm `Protocol` implementations |
| 20 | + core/ -- `EvmWormholeCore` implementation |
| 21 | + tokenBridge/ -- `EvmTokenBridge` implementation |
| 22 | + cctp/ `EvmCircleBridge` implementation |
| 23 | + ... |
| 24 | + src/ -- Contains the Evm implementations for `Platform`, `Chain`, `Address`, etc... |
| 25 | + solana/ -- Contains Solana `Platform` and `Protocol` implementations |
| 26 | + etc... |
| 27 | +
|
| 28 | +sdk/ -- Metapackage that depeneds on the rest of the packages, meant to be a simpler way to install/use. Exports packages in a way that allows for tree shaking unused packages and splitting chunks. |
| 29 | +
|
| 30 | +examples/ -- Examples, also used for README string replace |
110 | 31 | ``` |
111 | | ---> |
112 | | - |
113 | | - |
114 | | -## WormholeTransfer |
115 | | - |
116 | | -Holds a reference to ChainContexts |
117 | | - |
118 | | -Holds details about the transfer |
119 | | - |
120 | | -Provides methods to step through the transfer process |
121 | | - |
122 | | -## Glossary |
123 | | - |
124 | | -- Network |
125 | | - Mainnet, Testnet, Devnet |
126 | | -- Platform |
127 | | - A chain or group of chains within the same ecosystem that share common logic (e.g. EVM, Cosmwasm, etc) |
128 | | -- Platform Context |
129 | | - A class which implements a standardized format and set of methods. It may include additional chain-specific methods and logic. |
130 | | -- Protocol |
131 | | - A cross-chain application built on top of Wormhole (the core contracts are also considered a module) |
132 | | -- Universal Address |
133 | | - A 32-byte address, used by the wormhole contracts |
134 | | -- Native Address (I think this should be called "Platform Address") |
135 | | - An address in the standard chain-specific format |
136 | | -- Native |
137 | | - The "home" chain (e.g. ETH is native to Ethereum) |
138 | | -- Foreign |
139 | | - A non-native chain (e.g. ETH is foreign to Moonbeam) |
140 | | -- VAA (Verified Action Approval) |
141 | | - The core messaging primitive in Wormhole, it contains information about a message and a payload encoded as bytes. Once finality is achieved and it is observed by the majority of the guardians, it is signed and can then be used to complete a transfer on the destination chain |
142 | | -- Payload |
143 | | - Bytes that can be passed along with any wormhole message that contain application-specific data |
144 | | -- Finality/Finality Threshold |
145 | | - The required number of blocks to wait until a VAA is produced |
146 | | - |
147 | | -# Discussion |
148 | | - |
149 | | - |
150 | | -## What's the purpose of the Wormhole class? |
151 | | - |
152 | | -Wormhole class provides the main interface to do _everything_ |
153 | | - |
154 | | -- Registers Platforms to access later -- constructor |
155 | | -- Provides access to PlatformContexts -- getContext(ChainName) |
156 | | -- Provides "shortcuts" to start a WormholeTransfer -- tokenTransfer/nftTransfer/cctp/... |
157 | | -- Helpers for getting VAAs? or generally querying the API? |
158 | | -- Abstract away chain-specific logic for easy mode access to methods |
159 | | - |
160 | | -## What do we want from a PlatformContext and how is that different from a provider / common utilities for a given platform? |
161 | | - |
162 | | -Provides Platform specific logic for a set of things |
163 | | - |
164 | | -- Register Modules (contract/app specific functionality) |
165 | | -- Translates Platform specific stuff to generic stuff (e.g. ethers.Provider => RPC connection) |
166 | | -- Deals with Platform specific interaction w/ chain (approve on eth, postvaa on sol, ...) |
167 | | -- Implements standardized method format |
168 | | - |
169 | | -## What's the relationship between platforms/chains/providers? |
170 | | - |
171 | | -- A Platform provides the logic for all chains that run on that platform |
172 | | -- A Chain provides consts (rpc/contract addresses/chain specific overrides) |
173 | | -- A Provider is just an RPC connection and is held by the Chain. Providers are an implementation detail. |
174 | | - |
175 | | -## What's a signer vs. a wallet? Should signers have a provider (my answer: no)? |
176 | | - |
177 | | -- A Signer is an interface to sign transactions |
178 | | -- It _may_ be backed by a wallet but not necessarily, as long as it fulfils the interface |
179 | | - |
180 | | -## Can we provide some way to make other non-standard applications available to use through the WormholeTransfer? |
181 | | - |
182 | | -Say I have an app that defines its own protocol, can I provide something that adheres to the WormholeTransfer interface so a dev can install it and call it like the TokenTransfer? |
183 | | - |
184 | | - |
185 | | -# Outstanding Questions: |
186 | | - |
187 | | -What is the preferred terminology to refer to either end of a cross-chain message: from/to, source/target or origin/destination? |
188 | 32 |
|
189 | | -What is the preferred terminology for the core Wormhole layer? (i.e. Core Contracts or Wormhole Contracts) |
| 33 | +# Platform Interfaces |
190 | 34 |
|
191 | | -Should we namespace export base/definitions? |
| 35 | +Several interfaces should be available for each platform supported. |
192 | 36 |
|
193 | | -How should we think about xchain concepts without having xchain context? |
| 37 | +- A `Platform` is a blockchain runtime, often shared across a number of chains (e.g. `Evm` platform for `Ethereum`, `Bsc`, `Polygon`, etc ...). |
| 38 | +- A `Chain` is a specific blockchain, potentially with overrides for slight differences in the platform implementation. |
| 39 | +- A `Signer` is an interface that provides a callback to `sign` or `signAndSend` one or more transaction objects. |
| 40 | +- An `Address` provides parsing/formatting/conversion for platform specific addresses. |
194 | 41 |
|
195 | | - e.g. |
196 | | - // need to implement universal univeral decoder? |
197 | | - given eth address, and without installing evm platform, how do i turn it into a solana wrapped token without knowing how to fmt the address? |
| 42 | +# Protocol Interfaces |
198 | 43 |
|
199 | | - // neet to tweak contracts on sol to support !ATA? |
200 | | - given an xfer from eth=>sol, and without installing sol platform, how do i determine the ATA? |
| 44 | +A Protocol (fka `Module`) is a specific application, it provides a set of methods that can be called to accomplish some action (e.g. `TokenBridge` allows `transfer`/`redeem`/`getWrappedAsset`, etc...) |
201 | 45 |
|
| 46 | +To allow platform agnostic access to Protocols, each Platform that provides the protocol should have its own implementation. |
202 | 47 |
|
203 | | -What is the benefit of costmap vs single fat object |
204 | 48 |
|
205 | | -Why is network duped across platform/chaincontext/contracts? |
0 commit comments