Skip to content

Commit 9506279

Browse files
barnjaminbarnjamin
authored
New SDK Interfaces (#26)
1 parent e7a667d commit 9506279

File tree

2,133 files changed

+318394
-82718
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

2,133 files changed

+318394
-82718
lines changed

‎.github/workflows/build.yml

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
name: Node.js CI
2+
on: [push]
3+
jobs:
4+
build:
5+
runs-on: ubuntu-latest
6+
steps:
7+
- uses: actions/checkout@v3
8+
- name: Use Node.js
9+
uses: actions/setup-node@v3
10+
with:
11+
node-version: '18.x'
12+
- run: npm ci
13+
- run: npm run build --if-present
14+
- run: npm test
15+
# - run: cd core/tokenRegistry && npx ts-node src/scripts/checkForeignAssetConfig.ts

‎.gitignore

+7-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
1+
.turbo/
2+
build/
3+
dist/
14
node_modules/
2-
.env
5+
.env
6+
tsconfig-build.tsbuildinfo
7+
tsconfig.tsbuildinfo
8+
__tests__/staging

‎.prettierrc

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"tabWidth": 2,
3+
"printWidth": 100,
4+
"singleQuote": false,
5+
"trailingComma": "all",
6+
"semi": true
7+
}

‎DESIGN.md

+205
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
Design Document for Wormhole SDK
2+
---------------------------------
3+
4+
# Organization
5+
6+
Code is organized into workspaces so that each can be its own module.
7+
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+
93+
The `getRpc` method is the only platform specific thing _required_ to implement.
94+
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+
```
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)
110+
```
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+
189+
What is the preferred terminology for the core Wormhole layer? (i.e. Core Contracts or Wormhole Contracts)
190+
191+
Should we namespace export base/definitions?
192+
193+
How should we think about xchain concepts without having xchain context?
194+
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?
198+
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?
201+
202+
203+
What is the benefit of costmap vs single fat object
204+
205+
Why is network duped across platform/chaincontext/contracts?

0 commit comments

Comments
 (0)