sdk/js: readme, changelog, license
Change-Id: Id47bb140c4c89f192e5373600b271eaf8c6853f8
This commit is contained in:
Evan Gray
parent
5eea4cc51b
commit
848d8d1462
|
|
@ -1,80 +1 @@
|
|||
# Getting Started with Create React App
|
||||
|
||||
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
|
||||
|
||||
## Available Scripts
|
||||
|
||||
In the project directory, you can run:
|
||||
|
||||
### `npm start`
|
||||
|
||||
Runs the app in the development mode.\
|
||||
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
|
||||
|
||||
The page will reload if you make edits.\
|
||||
You will also see any lint errors in the console.
|
||||
|
||||
### `npm test`
|
||||
|
||||
_Note: this first runs `build-contracts`_
|
||||
|
||||
Launches the test runner in the interactive watch mode.\
|
||||
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
|
||||
|
||||
### `npm run build`
|
||||
|
||||
_Note: this first runs `build-contracts`_
|
||||
|
||||
Builds the app for production to the `build` folder.\
|
||||
It correctly bundles React in production mode and optimizes the build for the best performance.
|
||||
|
||||
The build is minified and the filenames include the hashes.\
|
||||
Your app is ready to be deployed!
|
||||
|
||||
See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
|
||||
|
||||
### `npm run build-contracts`
|
||||
|
||||
_Note: this requires `/ethereum` to have been installed; you may see an error if you have not yet run `npm ci` there_
|
||||
|
||||
This runs the build in the ethereum folder, copies the compiled contracts, and runs typechain on them. This is automatically run on `postinstall`
|
||||
|
||||
### `npm run eject`
|
||||
|
||||
**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
|
||||
|
||||
If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
|
||||
|
||||
Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
|
||||
|
||||
You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
|
||||
|
||||
## Learn More
|
||||
|
||||
You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
|
||||
|
||||
To learn React, check out the [React documentation](https://reactjs.org/).
|
||||
|
||||
### Code Splitting
|
||||
|
||||
This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)
|
||||
|
||||
### Analyzing the Bundle Size
|
||||
|
||||
This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)
|
||||
|
||||
### Making a Progressive Web App
|
||||
|
||||
This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
|
||||
|
||||
### Advanced Configuration
|
||||
|
||||
This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)
|
||||
|
||||
### Deployment
|
||||
|
||||
This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)
|
||||
|
||||
### `npm run build` fails to minify
|
||||
|
||||
This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)
|
||||
# Example Token Bridge UI
|
||||
|
|
|
|||
|
|
@ -0,0 +1,5 @@
|
|||
# Changelog
|
||||
|
||||
## 0.0.1
|
||||
|
||||
Initial release
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
Copyright 2020 Wormhole Project Contributors
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
|
@ -0,0 +1,208 @@
|
|||
# Wormhole SDK
|
||||
|
||||
> Note: This is a pre-alpha release and in active development. Function names and signatures are subject to change.
|
||||
|
||||
## What is Wormhole?
|
||||
|
||||
[Wormhole](https://wormholenetwork.com/) allows for the transmission of arbitrary data across multiple blockchains. Wormhole currently supports the following platforms:
|
||||
|
||||
- Solana
|
||||
- Ethereum
|
||||
- Terra
|
||||
- Binance Smart Chain
|
||||
|
||||
Wormhole is, at its base layer, a very simple protocol. A Wormhole smart contract has been deployed on each of the supported blockchains, and users can emit messages in the Wormhole Network by submitting data to the smart contracts. These messages are quite simple and only have the following six fields.
|
||||
|
||||
- _emitterChain_ - The blockchain from which this message originates.
|
||||
- _emitterAddress_ - The public address which submitted the message.
|
||||
- _consistencyLevel_ - The number of blocks / slots which should pass before this message is considered confirmed.
|
||||
- _timestamp_ - The timestamp when the Wormhole Network confirmed the message.
|
||||
- _sequence_ - An incrementing sequence which denotes how many messages this _emitterAddress_ has emitted.
|
||||
- _payload_ - The arbitrary contents of this message.
|
||||
|
||||
Whenever a wormhole contract processes one of these messages, participants in the Wormhole Network ( individually known as **Guardians** ), will observe the transaction and create a **SignedVAA** (Signed Verifiable Action Approval) once the transaction has reached the specified confirmation time on the emitter chain.
|
||||
|
||||
The SignedVAA is essentially an affirmation from the Wormhole Network that a transaction has been finalized on the emitter chain, and that any dependent actions on other chains may proceed.
|
||||
|
||||
While simple, the Wormhole Protocol provides a powerful base layer upon which many 'bridge' applications can be built. Because Wormhole is capable of verifying arbitrary data, bridges utilizing it are able to transfer native currencies, tokens, NFTs, oracle data, governance votes, and a whole host of other forms of decentralized data.
|
||||
|
||||
## How the Core Wormhole Bridge Works
|
||||
|
||||
The core Wormhole bridge operates by running smart contracts on both the _Source Chain_ (where the data currently resides) and the _Target Chain_ (where the data will be moved), and generally follows this workflow:
|
||||
|
||||
1) An end user or another smart contract publishes a message using the Bridge Contract on the Source Chain.
|
||||
|
||||
2) The Wormhole Network observes this transaction and issues a SignedVAA once it crosses its confirmation threshold.
|
||||
|
||||
3) An off-chain process collects the SignedVAA and submits it in a transaction to the Bridge Contract on the Target Chain, which can parse and verify the message.
|
||||
|
||||
## How the Wormhole Token Bridge Works
|
||||
|
||||
It is important to note that the Wormhole Token Bridge is not, strictly speaking, part of the Wormhole protocol, but rather a bridge on top of it. However, as token transfers are such an important use-case of the bridge, it is built and packaged as part of the Wormhole SDK.
|
||||
|
||||
The Token Bridge works in the same fashion as above, leveraging the Core Bridge to publish messages. However, there are actually two different functions in the token bridge: Attest and Transfer.
|
||||
|
||||
### Attest
|
||||
|
||||
Attestation is the process by which a token is 'registered' with the token bridge. Before being transferred, tokens must first be attested on their **Origin Chain** and have corresponding wrapped tokens created on the **Foreign Chain** to which they will be transferred. Attesting on the Origin Chain will create requisite addresses and metadata that will allow the wrapped asset to exist on Foreign Chains.
|
||||
|
||||
### Transfer
|
||||
|
||||
Once attested, tokens are mapped from their Native Chain to 'wrapped' assets on the Foreign Chains. Transferring an Ethereum-native token to Solana will result in a 'wrapped asset' on Solana, and transferring that same asset back to Ethereum will restore the native token.
|
||||
|
||||
It is important to note that Wormhole wrapped tokens are distinct from and incompatible with tokens wrapped by other bridges. Transferring a token which was wrapped by a different bridge will not redeem the native token, but rather will result in a 'double-wrapped' token.
|
||||
|
||||
## Examples
|
||||
|
||||
### Attest
|
||||
|
||||
#### Solana to Ethereum
|
||||
|
||||
```js
|
||||
// Submit transaction - results in a Wormhole message being published
|
||||
const transaction = await attestFromSolana(
|
||||
connection,
|
||||
SOL_BRIDGE_ADDRESS,
|
||||
SOL_TOKEN_BRIDGE_ADDRESS,
|
||||
payerAddress,
|
||||
mintAddress
|
||||
);
|
||||
const signed = await wallet.signTransaction(transaction);
|
||||
const txid = await connection.sendRawTransaction(signed.serialize());
|
||||
await connection.confirmTransaction(txid);
|
||||
// Get the sequence number and emitter address required to fetch the signedVAA of our message
|
||||
const info = await connection.getTransaction(txid);
|
||||
const sequence = parseSequenceFromLogSolana(info);
|
||||
const emitterAddress = await getEmitterAddressSolana(SOL_TOKEN_BRIDGE_ADDRESS);
|
||||
// Fetch the signedVAA from the Wormhole Network (this may require retries while you wait for confirmation)
|
||||
const { signedVAA } = await getSignedVAA(
|
||||
WORMHOLE_RPC_HOST,
|
||||
CHAIN_ID_SOLANA,
|
||||
emitterAddress,
|
||||
sequence
|
||||
);
|
||||
// Create the wrapped token on Ethereum
|
||||
await createWrappedOnEth(ETH_TOKEN_BRIDGE_ADDRESS, signer, signedVAA);
|
||||
```
|
||||
|
||||
#### Ethereum to Solana
|
||||
|
||||
```js
|
||||
// Submit transaction - results in a Wormhole message being published
|
||||
const receipt = await attestFromEth(
|
||||
ETH_TOKEN_BRIDGE_ADDRESS,
|
||||
signer,
|
||||
tokenAddress
|
||||
);
|
||||
// Get the sequence number and emitter address required to fetch the signedVAA of our message
|
||||
const sequence = parseSequenceFromLogEth(receipt, ETH_BRIDGE_ADDRESS);
|
||||
const emitterAddress = getEmitterAddressEth(ETH_TOKEN_BRIDGE_ADDRESS);
|
||||
// Fetch the signedVAA from the Wormhole Network (this may require retries while you wait for confirmation)
|
||||
const { signedVAA } = await getSignedVAA(
|
||||
WORMHOLE_RPC_HOST,
|
||||
CHAIN_ID_ETH,
|
||||
emitterAddress,
|
||||
sequence
|
||||
);
|
||||
// On Solana, we have to post the signedVAA ourselves
|
||||
await postVaaSolana(
|
||||
connection,
|
||||
wallet,
|
||||
SOL_BRIDGE_ADDRESS,
|
||||
payerAddress,
|
||||
signedVAA
|
||||
);
|
||||
// Finally, create the wrapped token
|
||||
const transaction = await createWrappedOnSolana(
|
||||
connection,
|
||||
SOL_BRIDGE_ADDRESS,
|
||||
SOL_TOKEN_BRIDGE_ADDRESS,
|
||||
payerAddress,
|
||||
signedVAA
|
||||
);
|
||||
const signed = await wallet.signTransaction(transaction);
|
||||
const txid = await connection.sendRawTransaction(signed.serialize());
|
||||
await connection.confirmTransaction(txid);
|
||||
```
|
||||
|
||||
### Transfer
|
||||
|
||||
#### Solana to Ethereum
|
||||
|
||||
```js
|
||||
// Submit transaction - results in a Wormhole message being published
|
||||
const transaction = await transferFromSolana(
|
||||
connection,
|
||||
SOL_BRIDGE_ADDRESS,
|
||||
SOL_TOKEN_BRIDGE_ADDRESS,
|
||||
payerAddress,
|
||||
fromAddress,
|
||||
mintAddress,
|
||||
amount,
|
||||
targetAddress,
|
||||
CHAIN_ID_ETH,
|
||||
originAddress,
|
||||
originChain
|
||||
);
|
||||
const signed = await wallet.signTransaction(transaction);
|
||||
const txid = await connection.sendRawTransaction(signed.serialize());
|
||||
await connection.confirmTransaction(txid);
|
||||
// Get the sequence number and emitter address required to fetch the signedVAA of our message
|
||||
const info = await connection.getTransaction(txid);
|
||||
const sequence = parseSequenceFromLogSolana(info);
|
||||
const emitterAddress = await getEmitterAddressSolana(SOL_TOKEN_BRIDGE_ADDRESS);
|
||||
// Fetch the signedVAA from the Wormhole Network (this may require retries while you wait for confirmation)
|
||||
const { signedVAA } = await getSignedVAA(
|
||||
WORMHOLE_RPC_HOST,
|
||||
CHAIN_ID_SOLANA,
|
||||
emitterAddress,
|
||||
sequence
|
||||
);
|
||||
// Redeem on Ethereum
|
||||
await redeemOnEth(ETH_TOKEN_BRIDGE_ADDRESS, signer, signedVAA);
|
||||
```
|
||||
|
||||
#### Ethereum to Solana
|
||||
|
||||
```js
|
||||
// Submit transaction - results in a Wormhole message being published
|
||||
const receipt = await transferFromEth(
|
||||
ETH_TOKEN_BRIDGE_ADDRESS,
|
||||
signer,
|
||||
tokenAddress,
|
||||
amount,
|
||||
CHAIN_ID_SOLANA,
|
||||
recipientAddress
|
||||
);
|
||||
// Get the sequence number and emitter address required to fetch the signedVAA of our message
|
||||
const sequence = parseSequenceFromLogEth(receipt, ETH_BRIDGE_ADDRESS);
|
||||
const emitterAddress = getEmitterAddressEth(ETH_TOKEN_BRIDGE_ADDRESS);
|
||||
// Fetch the signedVAA from the Wormhole Network (this may require retries while you wait for confirmation)
|
||||
const { signedVAA } = await getSignedVAA(
|
||||
WORMHOLE_RPC_HOST,
|
||||
CHAIN_ID_ETH,
|
||||
emitterAddress,
|
||||
sequence
|
||||
);
|
||||
// On Solana, we have to post the signedVAA ourselves
|
||||
await postVaaSolana(
|
||||
connection,
|
||||
wallet,
|
||||
SOL_BRIDGE_ADDRESS,
|
||||
payerAddress,
|
||||
signedVAA
|
||||
);
|
||||
// Finally, redeem on Solana
|
||||
const transaction = await redeemOnSolana(
|
||||
connection,
|
||||
SOL_BRIDGE_ADDRESS,
|
||||
SOL_TOKEN_BRIDGE_ADDRESS,
|
||||
payerAddress,
|
||||
signedVAA,
|
||||
isSolanaNative,
|
||||
mintAddress
|
||||
);
|
||||
const signed = await wallet.signTransaction(transaction);
|
||||
const txid = await connection.sendRawTransaction(signed.serialize());
|
||||
await connection.confirmTransaction(txid);
|
||||
```
|
||||
Loading…
Reference in New Issue