From be835d43f9b4e3617bdd07bf943d420810ea3832 Mon Sep 17 00:00:00 2001 From: Eric Wong Date: Tue, 4 Oct 2022 15:59:22 -0500 Subject: [PATCH] start documentation for xmint --- src/projects/xmint/client.md | 33 +++++++++++++++++++++++++++ src/projects/xmint/overview.md | 37 +++++++++++++++++++++++++++++++ src/projects/xmint/xMintEVM.md | 0 src/projects/xmint/xMintSolana.md | 0 4 files changed, 70 insertions(+) create mode 100644 src/projects/xmint/client.md create mode 100644 src/projects/xmint/overview.md create mode 100644 src/projects/xmint/xMintEVM.md create mode 100644 src/projects/xmint/xMintSolana.md diff --git a/src/projects/xmint/client.md b/src/projects/xmint/client.md new file mode 100644 index 0000000..acc13d7 --- /dev/null +++ b/src/projects/xmint/client.md @@ -0,0 +1,33 @@ +# xMint Client + +Let's walk through a few of the elements of the xMint client you'll see in the project folder: + +## [Orchestrator.ts](https://github.com/wormhole-foundation/xdapp-book/blob/main/projects/xmint/orchestrator.ts) +A Typsecript client that provides a chain agnostic way to deploy and call the functions of xMint contracts by utilizing EVM.ts and Solana.ts. + +## [EVM.ts](https://github.com/wormhole-foundation/xdapp-book/blob/main/projects/xmint/handlers/evm.ts) +A Typsecript client that deploys and calls the functions of the EVM contracts. + +## [Solana.ts](https://github.com/wormhole-foundation/xdapp-book/blob/main/projects/xmint/handlers/solana.ts) +A Typescript client that deploys and calls the functions of the Solana contracts. + +## Deploy +Compiles and deploys the contracts using the chain appropriate tools. The deployed addresses are stored to be used later. + +For EVM, this is done using [forge](https://getfoundry.sh) and for Solana, this is done using [Anchor](https://www.anchor-lang.com/). + +## Register App +Takes the deployed contract address from the target chain and registers it on the source chain. No Wormhole interaction is necessary for this step. + +Takes the deployed token address from the target chain and attests it on the source chain. A Wormhole token attestation interaction is necessary for this step. + + +## Buy Token + + + +## Sell Token + + + +## Balance \ No newline at end of file diff --git a/src/projects/xmint/overview.md b/src/projects/xmint/overview.md new file mode 100644 index 0000000..c70261f --- /dev/null +++ b/src/projects/xmint/overview.md @@ -0,0 +1,37 @@ +# xMint + +The xMint project is a sample project that completes one of the more common cross-chain user interactions: user stays on their native chain and swap a native token for another chain's native token. + +Behind the scenes of what the users sends and receives is a string of Wormhole interactions described in high level below + +1. User sends native token to xDapp. +2. xDapp initiates a Contract Controlled Transfer to corresponding contract on destination chain that contains both the user's tokens and a data payload. +3. Corresponding contract on destination chain verifies and parses VAA to perform the user's intended swap. +4. Corresponding contract on destination chain initiates a token transfer to user's wallet. + +Before you get started with this project, make sure you have a local Wormhole Guardian Network running (either [WLV](../../development/wormhole-local-validator.md) or [Tilt](../../development/tilt/overview.md)). If you're running WLV, you'll also need to spin up EVM0 and Solana so there is a EVM and Solana chain to send messages and tokens back and forth. + +Let's break down the files you're going to find in the [xMint](https://github.com/wormhole-foundation/xdapp-book/tree/main/projects/xmint) folder. + + +### Chains + +The `chains/` folder contains the source code that's actually being deployed to both the EVM and Solana chains which are organized in the `evm/` and `solana/` folders respectively. + +Each of these folders are organized according to best practices associated with building projects on each chain -- i.e. for EVM, the `.src/` folder contains (1) `Wormhole` which has all the contract interfaces needed to interact with Wormhole Core and Token Bridge and (2) `xMint.sol` which is the main contract defining the application. + +A more in depth breakdown of the EVM code is [here](./xMintEVM.md) and the Solana code is [here](./xMintSolana.md). + +### Tests + +We have a very simple test script written in bash, but it's less of a test script and more of a happy path walkthrough. It makes uses of Orchestrator.js (see below) to call the functions on our EVM and Solana contract in order. + +To start, deploy the code, register the applications on each chain and then send a message. + +### Orchestrator + +Orchestrator is a ts client that takes arguments from the command line to call various functions on our contract. We'll break down everything orchestator does and the associated handlers [here](./client.md). + +### xdapp.config.json + +This maintains some constants about the chains RPC endpoints, private keys used to deploy code, etc. It also includes the Wormhole RPC endpoint. \ No newline at end of file diff --git a/src/projects/xmint/xMintEVM.md b/src/projects/xmint/xMintEVM.md new file mode 100644 index 0000000..e69de29 diff --git a/src/projects/xmint/xMintSolana.md b/src/projects/xmint/xMintSolana.md new file mode 100644 index 0000000..e69de29