Skip to content

Commit 99425f0

Browse files
NithyamickeyNithyamickey
committed
Initial commit
0 parents  commit 99425f0

198 files changed

Lines changed: 37389 additions & 0 deletions

File tree

Some content is hidden

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

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
name: Bug report
3+
about: Submit a bug ticket if you have an issue. If you're a user, check out the Wormhole Discord server below for faster assistance.
4+
title: ''
5+
labels: 'bug'
6+
assignees: ''
7+
---
8+
<!--- Fill out the fields if you're an integrator or contributor. -->
9+
10+
## Description and context
11+
<!--- Provide a detailed description of the problem to expedite the process. -->
12+
13+
14+
## Steps to reproduce
15+
<!--- Describe what happened step by step. -->
16+
<!--- If applicable, provide a link to a live example or include code to reproduce. -->
17+
18+
1.
19+
2.
20+
3.
21+
22+
## Experienced behavior
23+
<!--- Describe what happened after the last step. -->
24+
25+
26+
## Expected behavior
27+
<!--- Describe what was expected to happen instead. -->
28+
29+
30+
## Solution recommendation
31+
<!--- Not mandatory, but feel free to recommend a way fix the issue. -->
32+

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Wormhole Official Discord
4+
url: https://discord.gg/wormholecrypto
5+
about: If you're a user, this is the fastest way to get help. Do not give your wallet private key or mnemonic words to anyone.

‎.github/ISSUE_TEMPLATE/task.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
name: Task
3+
about: Create a regular work item to be picked up by a contributor.
4+
title: ''
5+
labels: ''
6+
assignees: ''
7+
8+
---
9+
10+
## Description and context
11+
<!--- Write a description or todo list as the scope. A task should be: -->
12+
<!--- Actionable: can be acted on right away. -->
13+
<!--- Clearly defined scope: has precise limits/boundaries. -->
14+
<!--- Small scope: break complex tasks into smaller ones if they involve multiple system parts, multiple people/PRs, or parallelizable work. -->
15+
16+
## Definition of done
17+
<!--- Describe completion: e.g. code merged, deployment is done, or release published etc. -->

‎.github/dependabot.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# To get started with Dependabot version updates, you'll need to specify which
2+
# package ecosystems to update and where the package manifests are located.
3+
# Please see the documentation for all configuration options:
4+
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
5+
6+
version: 2
7+
updates:
8+
- package-ecosystem: "cargo"
9+
directory: "/"
10+
schedule:
11+
interval: "weekly"
12+
- package-ecosystem: "npm"
13+
directory: "/"
14+
schedule:
15+
interval: "weekly"
16+
- package-ecosystem: "github-actions"
17+
directory: "/"
18+
schedule:
19+
interval: "weekly"

‎CONTRIBUTING.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# Contributing to Wormhole Scaffolding
2+
3+
:pray: Thank you for spending some time to contribute! :pray:
4+
5+
We hope to outline some clear guidelines for contributing. This repository
6+
hopes to achieve its goal of showcasing many examples of [Wormhole]
7+
integrations. **If we missed any important aspects of contributing in this
8+
document, please submit a [pull request] to modify this document.**
9+
10+
Almost everything starts with a Github issue. And if your issue has a solution,
11+
it will end up being a pull request. The different types of issues are listed
12+
in the table of contents.
13+
14+
## Table of Contents
15+
16+
- [Structure]
17+
- [docs]
18+
- [evm]
19+
- [solana]
20+
- [Issues]
21+
- [Reporting Bugs] :bug:
22+
- [Missing or Incorrect Documentation] :page_with_curl:
23+
- [New Networks] :computer:
24+
- [New Examples] :alien:
25+
- [Help Wanted] :heart_eyes:
26+
- [Pull Requests]
27+
- [Questions]
28+
- [Final Words]
29+
30+
## Structure
31+
32+
Currently we aim to structure this repository like the [Wormhole] repository,
33+
where each blockchain network has its own subdirectory. Each subdirectory will
34+
try to resemble how a typical repository looks for that specific network.
35+
36+
### Docs
37+
38+
Whitepapers for each example exist here. If there are any whitepapers missing
39+
entirely or any info specific to a particular implementation is missing or wrong,
40+
please see [Missing or Incorrect Documentation] on how to submit an issue.
41+
42+
### EVM
43+
44+
We have put together the EVM (Ethereum Virtual Machine) directory assuming a
45+
smart contract structure similar to how `forge init` creates your environment.
46+
Here are the subdirectories:
47+
48+
- `forge-scripts` - Useful scripts written in Solidity.
49+
- `forge-test` - Scripts written in Solidity meant to be run using
50+
`forge test`.
51+
- `src/modules` - Work-in-progress modules that will eventually become dependencies
52+
that exist as an `npm` library or as a `forge` submodule.
53+
- `shell-scripts` - Useful shell scripts.
54+
- `src` - Smart contract source code, separated by each example (enumerated).
55+
- `ts-test` - Scripts written in Typescript ([TS-Mocha]) using [ethers.js] to
56+
interact with smart contracts deployed to `anvil` as a mainnet fork.
57+
58+
Please read the [evm README] for more details.
59+
60+
### Solana
61+
62+
We have put together the Solana directory assuming a program structure similar
63+
to how `anchor init` creates your environment. Because of this, all of these
64+
programs are written assuming the [Anchor] framework. Here are the
65+
subdirectories:
66+
67+
- `dependencies` - Wormhole-related artifacts live here (built from the
68+
[Wormhole] repo).
69+
- `modules` - Work-in-progress modules that will eventually become dependencies
70+
that exist as a `cargo` library.
71+
- `programs` - Program source code, separated by each example (enumerated).
72+
- `ts` - Web3 SDK and scripts written in Typescript ([TS-Mocha]) to interact
73+
with programs loaded in a Solana local validator run with `anchor test`.
74+
75+
Please read the [Solana README] for more details.
76+
77+
## Issues
78+
79+
These are the different categories of issues that exist in this repository.
80+
Some of these issues may be marked with "good first issue," which is an
81+
indication that the issue is good for a newcomer to Wormhole or blockchain
82+
development in general. And if for some reason an issue is not relevant to
83+
Wormhole integrations, an issue may be marked as "invalid."
84+
85+
You can find the list of issues
86+
[here](https://github.com/certusone/wormhole-scaffolding/issues).
87+
88+
### Reporting Bugs
89+
90+
A bug in our examples constitutes anything that has undesirable behavior. This
91+
includes (and is not limited to) malfunctioning methods (unexpected
92+
state-changes and output), vulnerabilities (re-entrancy, fake account
93+
injection, etc) and undefined behavior.
94+
95+
With vulnerabilities, we hope to illustrate as much as we can with protections
96+
against known vulnerabilities. We encourage contributors to add more test
97+
coverage!
98+
99+
If a potential bug is found, be sure to write specifically:
100+
101+
- What the bug is at a high-level
102+
- At least one example of how the bug can be exploited
103+
- A potential solution (either written in the issue or submitted
104+
[pull request])
105+
106+
Here are the list of [bug-related issues].
107+
108+
### Missing or Incorrect Documentation
109+
110+
Maybe missing or incorrect documentation is technically a bug. But we want to
111+
highlight the importance of documentation in a separate section.
112+
113+
We try our best to document everything. Because this repository warehouses
114+
examples of how to integrate with Wormhole, it is very important to describe
115+
the integration as clearly as possible. And each smart contract's
116+
implementation should reflect what is written in its respective whitepaper.
117+
118+
There may be some experimental features that we hope to capture in some
119+
examples. Because these example features may be changing frequently (e.g. if
120+
an example happens to reference a particular [Wormhole PR]), comments may not
121+
be accurate. These count as issues because if a feature changes, the example
122+
and its documentation needs to reflect these changes.
123+
124+
Here are some examples of some possible issues:
125+
126+
- Blockchain network environment set-up is wrong or outdated.
127+
- Comments do not reflect a field, method or object accurately.
128+
- Whitepaper mismatches implementation for a particular blockchain network.
129+
130+
Here is the list of [documentation issues].
131+
132+
### New Networks
133+
134+
Introducing a new network is a big task. In order to adequately cover a
135+
Wormhole integration with a new network, the examples start with the
136+
whitepapers found in the [docs]. All of the smart contracts written in
137+
this repository must reflect the business logic written in these whitepapers.
138+
139+
Test coverage (unit tests and integration tests) are a main part of these smart
140+
contract examples. Because we aim to demonstrate these Wormhole integrations
141+
sending messages to their other network counterparts, there should be
142+
exhaustive test coverage that illustrates all functionality before it can be
143+
considered deployable to mainnet. **We cannot accept a pull request for a new
144+
network if these tests are not met. We consider these examples incomplete.** If
145+
you need help writing specific tests, we can try to help out whenever we can.
146+
147+
We also recommend that the subdirectory representing a specific network to
148+
reflect how those applications exist in that specific ecosystem (e.g. our
149+
EVM contracts closely resemble the directory structure when `forge init` is
150+
called). This network's subdirectory should be inviting to other developers
151+
of that ecosystem.
152+
153+
Here is the list of [new network issues].
154+
155+
### New Examples
156+
157+
Coming up with a new example network of smart contracts to illustrate a new
158+
use case is really exciting! Some examples of how smart contracts across
159+
different networks talk to each other can be modeled using networking
160+
designs like [ZeroMQ Messaging Patterns] for example.
161+
162+
If you have a new idea for an example, you should start by writing a whitepaper
163+
with some pseudocode at least (targeting specific blockchain development
164+
languages is preferred, though).
165+
166+
Here is the list of [new example issues].
167+
168+
### Help Wanted
169+
170+
These issues can span any of the other categories of issues (new networks,
171+
documentation, etc). We will mark whichever issue with "help wanted" if we
172+
cannot prioritize working on these issues or if we do not have the
173+
background to fulfill these tasks.
174+
175+
Here is the list of [help wanted issues].
176+
177+
## Pull Requests
178+
179+
A pull request (PR) is a request to merge changes from one branch with another
180+
branch. Repositories each have their own procedures for submitting a PR, so
181+
we will outline a simple procedure that you should follow. Following this
182+
procedure will facilitate its merge to the `main` branch because the code
183+
owners will have an easier time understanding the code and documentation
184+
changes, as well as the thought process behind these changes.
185+
186+
**Only code owners can approve and merge a pull request.** Only one approval
187+
is required before the code is merged.
188+
189+
In the PR description, please describe the following:
190+
191+
1. The objective of the PR.
192+
- A high-level description of what the PR aims to do and why it should
193+
be merged into the `main` branch.
194+
- This objective may include an issue number, which you can reference by
195+
using a hash (#) followed by the issue number.
196+
2. How to review the PR.
197+
- Before a PR gets merged, code owners need to review and approve the
198+
changes before your branch gets merged into `main`. If the code owners have
199+
any problems reviewing the code, they will write comments referencing
200+
specific line numbers. You should then respond to by either writing a
201+
comment in response or checking in another commit reflecting the code
202+
owner's comment.
203+
204+
**If there are any continuous integration (CI) tests, the existing tests must
205+
pass.** These repository tests are very important for making sure that core
206+
logic existing in the `main` branch has not changed. If a CI test is changed
207+
or added, please be as descriptive as you can about what changed so we can pay
208+
close attention to what happened with the test.
209+
210+
You can find the list of pull requests
211+
[here](https://github.com/certusone/wormhole-scaffolding/pulls).
212+
213+
## Questions
214+
215+
Currently the only spot we can take questions is if there is a [github issue]
216+
outlining the problem. We will try to answer all questions. But keep in mind
217+
that more specific questions (with examples if appropriate) will probably be
218+
addressed sooner than others. Questions too vague may be marked as "won't fix."
219+
220+
## Final Words
221+
222+
Again, thank you for your contributions to the Wormhole Scaffolding repository.
223+
This repository becomes better when more of the community participates in its
224+
development.
225+
226+
[anchor]: https://www.anchor-lang.com/
227+
[bug-related issues]: https://github.com/certusone/wormhole-scaffolding/labels/bug
228+
[docs]: #docs
229+
[documentation issues]: https://github.com/certusone/wormhole-scaffolding/labels/documentation
230+
[ethers.js]: https://docs.ethers.io/v5/
231+
[evm]: #evm
232+
[evm readme]: evm/README.md
233+
[final words]: #final-words
234+
[github issue]: https://github.com/certusone/wormhole-scaffolding/issues
235+
[issues]: #issues
236+
[help wanted]: #help-wanted
237+
[help wanted issues]: https://github.com/certusone/wormhole-scaffolding/labels/help%20wanted
238+
[missing or incorrect documentation]: #missing-or-incorrect-documentation
239+
[new examples]: #new-examples
240+
[new example issues]: https://github.com/certusone/wormhole-scaffolding/labels/new%20example
241+
[new networks]: #new-networks
242+
[new network issues]: https://github.com/certusone/wormhole-scaffolding/labels/new%network
243+
[pull request]: #pull-requests
244+
[pull requests]: #pull-requests
245+
[questions]: #questions
246+
[reporting bugs]: #reporting-bugs
247+
[solana]: #solana
248+
[solana readme]: solana/README.md
249+
[structure]: #structure
250+
[ts-mocha]: https://github.com/piotrwitek/ts-mocha
251+
[wormhole]: https://github.com/wormhole-foundation/wormhole
252+
[wormhole pr]: https://github.com/wormhole-foundation/wormhole/pulls
253+
[zeromq messaging patterns]: https://zguide.zeromq.org/docs/chapter2/#Messaging-Patterns

‎LICENSE‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Copyright 2022 Wormhole Project Contributors
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

‎README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Wormhole Scaffolding
2+
3+
This repository warehouses apps that integrate with Wormhole generic messaging and existing apps that use Wormhole message passing. These apps range in complexity and demonstrate how to organize your business logic in your smart contracts. These examples show the basic structure of an xdapp and how the wormhole works with the respective programming environment.
4+
Example repos also include tests to debug and deploy the dapps in local environment.
5+
6+
There are 3 example dapps that give a walkthrough on some of the core components of the wormhole messaging and portal token bridge.
7+
1. [Hello World](https://github.com/wormhole-foundation/wormhole-scaffolding/blob/main/docs/01_hello_world.md) -> [Solana](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/solana/programs/01_hello_world) | [EVM](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/evm/src/01_hello_world)
8+
2. [Hello Token](https://github.com/wormhole-foundation/wormhole-scaffolding/blob/main/docs/02_hello_token.md) -> [Solana](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/solana/programs/02_hello_token) | [EVM](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/evm/src/02_hello_token)
9+
3. [NFT Burn Bridging](https://github.com/wormhole-foundation/wormhole-scaffolding/blob/main/docs/03_nft_burn_bridging.md) -> [Solana](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/solana/programs/03_nft_burn_bridging) | [EVM](https://github.com/wormhole-foundation/wormhole-scaffolding/tree/main/evm/src/03_nft_burn_bridging)
10+
11+
## Prerequisites
12+
13+
### EVM
14+
15+
If your xChain app will require EVM smart contracts, we recommend using [Foundry tools](https://book.getfoundry.sh/getting-started/installation), which include `forge`, `anvil` and `cast` CLI tools.
16+
17+
### Solana
18+
19+
If your xChain app will require Solana programs, prepare your development environment by installing [Solana and Anchor dependencies](https://book.anchor-lang.com/getting_started/installation.html), which include `solana` and `anchor` CLI tools.
20+
21+
Anchor helps in abstracting solana architecture boilerplate code. However, it has its own challenges so you can still write programs in native rust, download ['rust-analyzer'](https://rust-analyzer.github.io/) to debug and write efficient rust.
22+
23+
### SUI
24+
25+
Install the `Sui` CLI. This tool is used to compile the contracts and run the tests.
26+
27+
```sh
28+
cargo install --locked --git https://github.com/MystenLabs/sui.git --rev 09b2081498366df936abae26eea4b2d5cafb2788 sui sui-faucet
29+
```
30+
31+
### Worm CLI
32+
33+
First, check out the [Wormhole](https://github.com/wormhole-foundation/wormhole) repo, then install the CLI tool by running:
34+
35+
```sh
36+
wormhole/clients/js $ make install
37+
```
38+
39+
`worm` is the swiss army knife for interacting with wormhole contracts on all
40+
supported chains, verifying payloads, and generating VAAs.
41+
Head to [Cli docs](https://docs.wormhole.com/wormhole/reference/cli-docs) to learn more.
42+
43+
## Build and Test
44+
45+
Each directory represents Wormhole integrations for specific blockchain networks. Please navigate
46+
to a network subdirectory to see more details on building and testing.
47+
If you have questions or doubts join the [wormhole discord](https://discord.gg/8dRSUqAW).

0 commit comments

Comments
 (0)