diff --git a/docs/build/isc/v1.0.0-rc.6/docs/how-tos/send-ERC20-across-chains.md b/docs/build/isc/v1.0.0-rc.6/docs/how-tos/send-ERC20-across-chains.md index a880be90304..1c5ec2b54c5 100644 --- a/docs/build/isc/v1.0.0-rc.6/docs/how-tos/send-ERC20-across-chains.md +++ b/docs/build/isc/v1.0.0-rc.6/docs/how-tos/send-ERC20-across-chains.md @@ -2,10 +2,10 @@ ## Introduction -To enable cross-chain transfers of existing ERC20 tokens such as wSMR and wIOTA (wrapped versions of the native gas tokens SMR and IOTA on ShimmerEVM and IOTA EVM respectively), LayerZero OFT V2 is utilized. For testing purposes, Sepolia is chosen as the source chain, while the BNB testnet is chosen as the destination chain. +[LayerZero OFT V2](https://docs.layerzero.network/v2) enables cross-chain transfers of existing ERC20 tokens, such as wSMR and wIOTA (wrapped versions of the native gas tokens SMR and IOTA on ShimmerEVM and IOTA EVM respectively). For testing purposes, Sepolia is chosen as the source chain, while the BNB testnet is chosen as the destination chain. -:::info -Clone the repository for Utilities for LayerZero OFT V2 from [here](https://github.com/iota-community/layerzero-oft-v2-utils). +:::info Community Libs +You can clone the Utilities for LayerZero OFT V2 from [IOTA Community GitHub Repository](https://github.com/iota-community/layerzero-oft-v2-utils). ::: ### Why Would a User Need to Send ERC20 Tokens Across Chains? @@ -14,139 +14,158 @@ Sending ERC20 tokens across chains allows users to leverage the strengths and un [**Use-case 1**](https://docs.layerzero.network/v2/developers/evm/oft/adapter) -To enable existing ERC20 tokens for cross-chain sending, both OFTAdapter and OFT contracts are needed. +#### Send Existing ERC20 Tokens Across Chains + +You need both the OFT Adapter and OFT contracts to enable existing ERC20 tokens for cross-chain sending, [**Use-case 2**](https://docs.layerzero.network/v2/developers/evm/oft/quickstart) -For new ERC20 tokens to be launched, the OFT standard can be leveraged to enable cross-chain sending without the need for an OFTAdapter. +#### Create New Cross-chain Fungible Tokens + +If you are about to launch a new ERC20 token, you can use the [OFT standard](https://docs.layerzero.network/v2/developers/evm/oft/quickstart) to enable cross-chain sending without the OFT Adapter. -### Using IOTA's Implementation of [Utilities for LayerZero OFT V2](https://github.com/iota-community/layerzero-oft-v2-utils) +### How To Use IOTA's Utilities for LayerZero OFT V2 -The Utilities for LayerZero OFT V2 facilitate cross-chain sending of ERC20 tokens between a source chain (e.g., Sepolia or ShimmerEVM testnet) and a destination chain (e.g., BNB testnet or IOTA EVM testnet). +The [Utilities for LayerZero OFT V2](https://github.com/iota-community/layerzero-oft-v2-utils) facilitate cross-chain sending of ERC20 tokens between a source chain (e.g., Sepolia or ShimmerEVM Testnet) and a destination chain (e.g., BNB Testnet or IOTA EVM Testnet). -:::tip -Further information: https://docs.layerzero.network/v2/developers/evm/gas-settings/options#option-types. +:::tip Further Information +You can learn more about the available options in the [Layer Zero Documentation](https://docs.layerzero.network/v2/developers/evm/gas-settings/options#option-types.). ::: -### Procedure to Send Tokens from Source Chain to Destination Chain and Vice Versa +### Send Tokens from One Source Chain to Another Destination Chain (and Vice Versa) -For existing ERC20 tokens that involve both the OFTAdapter contract (on the source chain) and the OFT contract (on the destination chain), the token sending procedure is as follows: +To send existing ERC20 tokens, you will need both the OFT Adapter contract on the source chain and the OFT contract on the destination chain. You should then use the following procedure: -1. **Approve Tokens**: The sender approves their ERC20 tokens for the OFTAdapter contract. -2. **Estimate Fee**: The sender calls the function `quoteSend()` of the OFTAdapter contract to estimate the cross-chain fee to be paid in native tokens on the source chain. -3. **Send Tokens**: The sender calls the function `send()` of the OFTAdapter contract to transfer tokens from the source chain to the destination chain. -4. **Optional - Wait for Finalization**: The sender can wait for transaction finalization on the destination chain using the library [@layerzerolabs/scan-client](https://www.npmjs.com/package/@layerzerolabs/scan-client#example-usage). +1. **Approve the tokens**: The sender must approve their ERC20 tokens for the OFT Adapter contract. +2. **Estimate the fee**: The sender calls the function `quoteSend()` of the OFT Adapter contract to estimate the cross-chain fee to be paid in native tokens on the source chain. +3. **Send the tokens**: The sender calls the function `send()` of the OFT Adapter contract to transfer tokens from the source chain to the destination chain. +4. **(Optional) Wait for Finalization**: The sender can wait for transaction finalization on the destination chain using the library [@layerzerolabs/scan-client](https://www.npmjs.com/package/@layerzerolabs/scan-client#example-usage). To send back the OFT-wrapped tokens on the destination chain to the source chain, the procedure is similar, except that the approval step is not needed: -1. **Estimate Fee**: The sender calls the function `quoteSend()` of the OFT contract to estimate the cross-chain fee to be paid in native tokens on the sender chain. +1. **Estimate the fee**: The sender calls the function `quoteSend()` of the OFT contract to estimate the cross-chain fee to be paid in native tokens on the sender chain. 2. **Send Tokens**: The sender calls the function `send()` of the OFT contract to transfer tokens from the destination chain back to the source chain. -3. **Optional - Wait for Finalization**: The sender can wait for transaction finalization on the destination chain using the library `@layerzerolabs/scan-client`. +3. **(Optional) Wait for Finalization**: The sender can wait for transaction finalization on the destination chain using the library `@layerzerolabs/scan-client`. + + +#### Sample Solidity code for OFT Adapter and OFT contracts in the folder `contracts-standard` +The [contracts-standard](https://github.com/iota-community/layerzero-oft-v2-utils/tree/main/contracts-standard) contains scripts to: +- Deploy the OFT Adapter and OFT contracts. +- Set your trusted peers. +- Set enforced options. +- Send tokens from the source chain to the destination chain, and vice versa. +### Install the Library -#### Sample Solidity code for OFTAdater and OFT contracts in folder `contracts-standard` -- Scripts for: - - Deploy OFTAdapter and OFT contracts - - Set trusted peer - - Set enforced options - - Send tokens from source chain to destination chain and vice versa +After you have cloned the [IOTA Community Utilities for LayerZero OFT V2 repository](https://github.com/iota-community/layerzero-oft-v2-utils/tree/main), you should run the following command to install: -## Installation ``` -$ yarn +yarn ``` -## Compile contracts +## Compile the Contracts -- In the standard implementation for ERC20, copy the folder `contracts-standard`to `contracts` and `contracts-wiota` to `contracts` for custom implementation. Then, run the command: +If you want to use the standard implementation for ERC20, copy the [`contracts-standard`](https://github.com/iota-community/layerzero-oft-v2-utils/tree/main/contracts-standard) folder to `contracts`. If you want to use a custom implementation, copy the [`contracts-wiota`](https://github.com/iota-community/layerzero-oft-v2-utils/tree/main/contracts-wiota) to `contracts`. Then, run the following command to compile the contracts: -``` - $ yarn compile +```bash +yarn compile ``` -## Configuration +### Set Your Configuration -The config is specified in the template file `.env.example` that needs to be copied to another file `.env`. +You should copy the template [`.env.example`](https://github.com/iota-community/layerzero-oft-v2-utils/blob/main/.env.example) file to a file called `.env`, and edit any of the configuration options you see fit. +```bash +cp .env.example .env +``` -## Deploy contracts +### Deploy the Contracts -### Deploy OFTAdapter on source chain (e.g. Sepolia) +## Deploy the OFT Adapter Contract On the Source Chain The OFT Adapter facilitates the expansion of an existing token to any supported blockchain as a native token, maintaining a unified global supply and inheriting all features of the OFT Standard. This intermediary contract manages the sending and receiving of pre-deployed tokens. For instance, when an ERC20 token is transferred from the source chain (Chain A), it gets locked in the OFT Adapter. Consequently, a corresponding token is minted on the destination chain (Chain B) through the paired OFT Contract. -``` -$ yarn deploy-oft-adapter-sepolia +```bash +yarn deploy-oft-adapter-sepolia ``` -Log output : +Expected log output : -``` -$ npx hardhat run scripts/deploy_oft_adapter.ts --network sepolia +```bash +npx hardhat run scripts/deploy_oft_adapter.ts --network sepolia Deployed MyOFTAdapter contract address: 0x4daa81978576cB91a2e1919960e90e46c2a6D586 Done in 6.67s. ``` -### Deploy OFT on destination chain (e.g. BNB testnet) +### Deploy OFT on the Destination Chain -``` -$ yarn deploy-oft-bnb-testnet +You can use the following command to deploy OFT on destination chain (e.g. BNB Testnet): + +```bash +yarn deploy-oft-bnb-testnet ``` -Log output : +Expected log output : -``` -$ npx hardhat run scripts/deploy_oft.ts --network bnbTestnet +```bash +npx hardhat run scripts/deploy_oft.ts --network bnbTestnet Deployed MyOFT contract address: 0xCc337C2e69F4Eb8EaBcf632a1fC5B8F729dC47F1 Done in 6.68s. ``` -## Set trusted peer (Optinal) +### (optional) Set the Trusted Peers -### On OFTAdapter (source chain, e.g. Sepolia) +### On OFTAdapter -``` -$ yarn set-peer-oft-adapter-sepolia +You can set the trusted peer in the source chain's OFT Adapter (e.g., Sepolia) using the following command: + +```bash +yarn set-peer-oft-adapter-sepolia ``` -Log output : +Expected log output : -``` -$ npx hardhat run scripts/set_peer_oft_adapter.ts --network sepolia +```bash +npx hardhat run scripts/set_peer_oft_adapter.ts --network sepolia setPeerMyOFTAdapter - oftAdapterContractAddress:0x4daa81978576cB91a2e1919960e90e46c2a6D586, lzEndpointIdOnDestChain:40102, oftContractAddress:0xCc337C2e69F4Eb8EaBcf632a1fC5B8F729dC47F1 MyOFTAdapter - setPeer tx: 0xc17e7a54d96325768b6427ce893d9b6b7ed04bd920089b63a3f96c005073e9c2 Done in 14.10s. ``` -### On OFT (destination chain, e.g. BNB testnet) +#### On OFT -``` -$ yarn set-peer-oft-bnb-testnet +You can add a trusted peer in the destination chain (e.g. BNB Testnet) using the following command: + +```bash +yarn set-peer-oft-bnb-testnet ``` -Log output : +Expected log output : -``` -$ npx hardhat run scripts/set_peer_oft.ts --network bnbTestnet +```bash +npx hardhat run scripts/set_peer_oft.ts --network bnbTestnet setPeerMyOFT - oftContractAddress:0xCc337C2e69F4Eb8EaBcf632a1fC5B8F729dC47F1, lzEndpointIdOnSrcChain:40161, oftAdapterContractAddress:0x4daa81978576cB91a2e1919960e90e46c2a6D586 MyOFT - setPeer tx: 0xb0012378ee14c9df5c9f86980dd9c96fc8aedb3c19d92c1d91a4259f3981ac35 Done in 4.66s. ``` -## Send origin tokens from source chain to destination chain +### Send the Origin Tokens from the Source Chain to the Destination Chain -``` -$ yarn send-oft-from-sepolia -``` -Log output : +You can use the following command to send tokens from the source chain to the destination chain: +```bash +yarn send-oft-from-sepolia ``` -$ npx hardhat run scripts/send_oft.ts --network sepolia + +Expected log output : + +```bash +npx hardhat run scripts/send_oft.ts --network sepolia sendOFT - oftAdapterContractAddress:0x5D7Cbc05fc6df2832c40023f1Eb2755628C51D81, oftContractAddress:0x075e512E25b45a3EaF8b432220F0Ca8D4e3c6a58, lzEndpointIdOnSrcChain:40161, lzEndpointIdOnDestChain:40102, gasDropInWeiOnDestChain:1000000000000000, executorLzReceiveOptionMaxGas:200000, receivingAccountAddress:0x5e812d3128D8fD7CEac08CEca1Cd879E76a6E028, sender: 0x57a4bd139fb673d364a6f12df9177a3f686625f3, amount:2 sendOFT - approve tx: 0x8fa692edb47b1ad9d21f60b0fa30993e5cd3abd78c3c56fb4f38db5f9b8ac369 sendOFT - estimated nativeFee: 0.000734209489447653 @@ -156,16 +175,19 @@ sendOFT - received tx on destination chain: 0xc2e5a4be8ae67718e817ff585a32765e39 ``` -## Send OFT-wrapped tokens back from destination chain to origin chain +### Send Oft-Wrapped Tokens Back From the Destination Chain to the Origin Chain -``` -$ yarn send-oft-back-from-bnb-testnet -``` +You can use the following command to send the OFT-wrapped tokens back to the origin chain: -Log output : +```bash +yarn send-oft-back-from-bnb-testnet ``` -$ npx hardhat run scripts/send_oft_back.ts --network bnbTestnet + +Expected log output : + +```bash +npx hardhat run scripts/send_oft_back.ts --network bnbTestnet sendOFTBack - oftAdapterContractAddress:0x5D7Cbc05fc6df2832c40023f1Eb2755628C51D81, oftContractAddress:0x075e512E25b45a3EaF8b432220F0Ca8D4e3c6a58, lzEndpointIdOnSrcChain:40161, lzEndpointIdOnDestChain:40102, gasDropInWeiOnDestChain:1000000000000000, executorLzReceiveOptionMaxGas:200000, receivingAccountAddress:0x57A4bD139Fb673D364A6f12Df9177A3f686625F3, sender: 0x5e812d3128D8fD7CEac08CEca1Cd879E76a6E028, amount:2 sendOFTBack - estimated nativeFee: 0.054815809525020364 sendOFTBack - send tx on source chain: 0x41bcf78b310dc1bbf9b4005f7412d995011c7815ad5af9cc26b37370e75bbfeb