From b5a88cf96e2301fe0c472e6b417682af095be37a Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 19 Feb 2025 15:43:07 -0600 Subject: [PATCH 01/14] First version of tutorial --- pages/stack/interop/tutorials/_meta.json | 2 +- .../tutorials/transfer-superchainERC20.mdx | 246 ++++++++++++------ public/tutorials/xfer-erc20.mts | 107 ++++++++ 3 files changed, 279 insertions(+), 76 deletions(-) create mode 100644 public/tutorials/xfer-erc20.mts diff --git a/pages/stack/interop/tutorials/_meta.json b/pages/stack/interop/tutorials/_meta.json index f69605cf5..fa773ef25 100644 --- a/pages/stack/interop/tutorials/_meta.json +++ b/pages/stack/interop/tutorials/_meta.json @@ -1,6 +1,6 @@ { "message-passing": "Interop message passing", - "transfer-superchainERC20": "Transferring a SuperchainERC20", + "transfer-superchainERC20": "Transferring SuperchainERC20 tokens", "deploy-superchain-erc20": "Issuing new assets with SuperchainERC20", "bridge-crosschain-eth": "Bridging native cross-chain ETH transfers", "relay-messages-cast": "Relaying interop messages using `cast`", diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index f7e574556..4aea1ccf6 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -1,5 +1,5 @@ --- -title: Transferring a SuperchainERC20 +title: Transferring SuperchainERC20 tokens lang: en-US description: Learn how to transfer a SuperchainERC20 between chains using L2ToL2CrossDomainMessenger. --- @@ -13,106 +13,202 @@ Please note that the OP Stack interoperability upgrade, required for crosschain # Transferring a SuperchainERC20 -This guide provides an overview of transferring `SuperchainERC20` tokens between chains. +This guide shows how to transfer `SuperchainERC20` tokens between chains programatically. + + + This tutorial provides step-by-step instructions for transferring `SuperchainERC20` tokens using code. + [See here](../superchain-erc20#how-it-works) for a detailed explanation of how this works. + ## Overview -Transferring SuperchainERC20 tokens between chains involves two main phases: +**Warning:** Always verify your addresses and amounts before sending transactions. +Cross-chain transfers cannot be reversed. -1. **Source Chain Operations** - * Mint tokens if needed - * Initiate the transfer using the bridge -2. **Destination Chain Operations** - * Relay the transfer message - * Verify the transfer completion +### What you'll build - - Always verify your addresses and amounts before sending transactions. Cross-chain transfers cannot be reversed. - +* A TypeScript application to transfer `SuperchainERC20` tokens between chains + +### What you'll learn + +* How to send `SuperchainERC20` tokens on the blockchain and between blockchains +* How to relay messages between chains + +## Prerequisites + +Before starting this tutorial, ensure your development environment meets the following requirements: + +### Technical knowledge + +* Intermediate TypeScript knowledge +* Understanding of smart contract development +* Familiarity with blockchain concepts + +### Development environment -## How it works - -This diagram illustrates the process of a SuperchainERC20 token transfer between chains. -Through the `L2ToL2CrossDomainMessenger` contract, tokens are burned on the source chain and a transfer message is emitted. -This message must then be relayed to the destination chain, where an equivalent amount of tokens will be minted to the specified recipient address - ensuring secure cross-chain transfers while maintaining the total token supply across all chains. - -```mermaid -sequenceDiagram - actor User - participant SourceChain - participant Bridge as L2ToL2CrossDomainMessenger - participant DestChain - - Note over User,DestChain: Step 1: Prepare Tokens - User->>SourceChain: Check token balance - alt - User->>SourceChain: Mint or acquire tokens - end - - Note over User,DestChain: Step 2: Initiate Transfer - User->>SourceChain: Approve bridge contract - User->>Bridge: Call sendERC20 - Bridge->>SourceChain: Burn tokens - Bridge-->>Bridge: Emit transfer message - - Note over User,DestChain: Step 3: Complete Transfer - User->>Bridge: Get message details - User->>Bridge: Relay message on destination - Bridge->>DestChain: Mint tokens to recipient - - Note over User,DestChain: Step 4: Verify - User->>DestChain: Check token balance -``` +* Unix-like operating system (Linux, macOS, or WSL for Windows) +* Node.js version 16 or higher +* Git for version control + +### Required tools + +The tutorial uses these primary tools: + +* Foundry: For issuing transactions +* TypeScript: For implementation +* Node: For running TypeScript code from the command line +* Viem: For blockchain interaction + + +## Directions - ### Prepare your tokens - Ensure you have tokens on the source chain using one of these methods: + ### Preparation - * Use existing tokens you already own - * Mint new tokens using the [SuperchainERC20 contract](https://github.com/ethereum-optimism/supersim/blob/main/contracts/src/L2NativeSuperchainERC20.sol) if you have minting permissions - * Acquire tokens through a supported exchange or transfer + You need onchain `SuperchainERC20` tokens. + You can [deploy your own token](./deploy-superchain-erc20), but in this tutorial we will use [`CustomSuperchainToken`](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8), existing `SuperchainERC20` token on the [Interop devnet](../tools/devnet). - ### Initiate the transfer + 1. Create environment variables for the RPC endpoints for the blockchains and the token address. - To start the transfer: + ```sh + RPC_DEV0=https://interop-alpha-0.optimism.io + RPC_DEV1=https://interop-alpha-1.optimism.io + TOKEN_ADDRESS=0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8 + ``` - 1. Choose the destination chain where you want to receive the tokens - 2. Specify the recipient address and the amount to transfer - 3. Call the bridge contract, which will: - * Lock or burn your tokens on the source chain - * Emit a message that will be used to mint tokens on the destination chain + 1. Set `PRIVATE_KEY` to the private key of an address that has [Sepolia ETH](https://cloud.google.com/application/web3/faucet/ethereum/sepolia). - ### Complete the transfer + ```sh + export PRIVATE_KEY=0x + MY_ADDRESS=`cast wallet address $PRIVATE_KEY` + ``` - To finalize the transfer on the destination chain: + 1. Send ETH to the two L2 blockchains. - 1. Get the message details from the source chain event - 2. Use the `L2ToL2CrossDomainMessenger` contract to relay the message - 3. The message relay will trigger the minting of tokens on the destination chain + ```sh + cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIVATE_KEY --value 0.02ether 0x7385d89d38ab79984e7c84fab9ce5e6f4815468a + cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIVATE_KEY --value 0.02ether 0x55f5c4653dbcde7d1254f9c690a5d761b315500c + ``` - - The transfer isn't complete until the message is successfully relayed on the destination chain. See the [technical reference guide](/stack/interop/tutorials/relay-messages-viem) for specific relay instructions. - + 1. Wait a few minutes until you can see the ETH [on the block explorer](https://sid.testnet.routescan.io/) for your address. - ### Verify completion +
+ Sanity check - After relaying the message: + ```sh + cast balance --ether $MY_ADDRESS --rpc-url $RPC_DEV0 + cast balance --ether $MY_ADDRESS --rpc-url $RPC_DEV1 + ``` +
- 1. Check your token balance on the destination chain - 2. Confirm the transferred amount matches what you sent - 3. The tokens should now be available for use on the destination chain - + 1. Obtain tokens on Interop devnet 0. + When using `CustomSuperchainToken` there are two ways to do this: + + - Use the [block explorer](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000) and a browser wallet to run the [faucet](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000#F6) function. + + - Use `cast` to call the `faucet` function. + + ```sh + cast send --rpc-url $RPC_DEV0 --private-key $PRIVATE_KEY $TOKEN_ADDRESS "faucet()" + ``` + +
+ + Sanity check -For detailed technical instructions including contract addresses, specific commands, and message relaying details, refer to our [technical reference guide](/stack/interop/tutorials/relay-messages-viem). + Run this command to check your token balance. -## Alternative methods + ```sh + cast call --rpc-url $RPC_DEV0 $TOKEN_ADDRESS "balanceOf(address)" $MY_ADDRESS | cast --from-wei + ``` -You can also use: +
-* [viem bindings/actions](/stack/interop/tutorials/relay-messages-viem) for TypeScript integration + ### Transfer tokens using TypeScript + + We are going to use a [Node](https://nodejs.org/en) project, to be able to use [`@eth-optimism/viem`](https://www.npmjs.com/package/@eth-optimism/viem) to send the executing message. + We use [TypeScript](https://www.typescriptlang.org/) to have type safety combined with JavaScript functionality. + + 1. Initialize a new Node project. + + ```sh + mkdir xfer-erc20 + cd xfer-erc20 + npm init -y + npm install --save-dev -y viem tsx @types/node @eth-optimism/viem + mkdir src + ``` + + 1. Edit `package.json` to add the `start` script. + + ```json + { + "name": "xfer-erc20", + "version": "1.0.0", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1", + "start": "tsx src/xfer-erc20.mts" + }, + "keywords": [], + "author": "", + "license": "ISC", + "type": "commonjs", + "description": "", + "devDependencies": { + "@eth-optimism/viem": "^0.3.2", + "@types/node": "^22.13.4", + "tsx": "^4.19.3", + "viem": "^2.23.3" + } + } + ``` + + 1. Create `src/xfer-erc20.mts`: + + ```solidity file=/public/tutorials/xfer-erc20.mts hash=19a948eeb482046afb1a55ccc5019599 + ``` + +
+ + Explanation + + ```solidity file=/public/tutorials/xfer-erc20.mts#L79-L84 hash=85f317d0cbe2b59e303e36a3e6154c62 + ``` + + Use `@eth-optimism/viem`'s `walletActionsL2().sendSuperchainERC20` to send the `SuperchainERC20` tokens. + Internally, this function calls [`SuperchainTokenBridge.sendERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol#L52-L78) to send the tokens. + + ```typescript file=/public/tutorials/xfer-erc20.mts#L88-L90 hash=cab6e961b558f4f5a7b877062b1cfa45 + ``` + + To relay a message we need the information in the receipt. + Also, we need to wait until the transaction with the relayed message is actually part of a block. + + ```typescript file=/public/tutorials/xfer-erc20.mts#L92-L94 hash=1da0981adb2fbd38cccf1b0602158418 + ``` + + A single transaction can send multiple messages. + But here we know we sent just one, so we look for the first one in the list. + + ```typescript file=/public/tutorials/xfer-erc20.mts#L96-L99 hash=b5ad9f0c44aee84742cd20c348fdb156 + ``` + + This is how you use `@eth-optimism/viem` to create an executing message. + +
+ + 1. Run the TypeScript program, and see the change in your `CustomSuperchainToken` balances. + + ```sh + npm start + ``` + + ## Next steps * Read the [Superchain Interop Explainer](/stack/interop/explainer#faqs) or check out this [Superchain interop design video walk-thru](https://www.youtube.com/watch?v=FKc5RgjtGes). +* Learn [how this works](/stack/interop/superchain-erc20). * Use [Supersim](/app-developers/tools/supersim), a local dev environment that simulates Superchain interop for testing applications against a local version of the Superchain. diff --git a/public/tutorials/xfer-erc20.mts b/public/tutorials/xfer-erc20.mts new file mode 100644 index 000000000..651a89112 --- /dev/null +++ b/public/tutorials/xfer-erc20.mts @@ -0,0 +1,107 @@ +import { + createWalletClient, + http, + publicActions, + getContract, + Address, +} from 'viem' +import { privateKeyToAccount } from 'viem/accounts' +import { interopAlpha0, interopAlpha1 } from '@eth-optimism/viem/chains' + +import { + walletActionsL2, + publicActionsL2, + createInteropSentL2ToL2Messages, +} from '@eth-optimism/viem' + +const tokenAddress = "0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8" +const balanceOf = { + "constant": true, + "inputs": [{ + "name": "_owner", + "type": "address" + }], + "name": "balanceOf", + "outputs": [{ + "name": "balance", + "type": "uint256" + }], + "payable": false, + "stateMutability": "view", + "type": "function" + } + +const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`) + +const wallet0 = createWalletClient({ + chain: interopAlpha0, + transport: http(), + account +}).extend(publicActions) + .extend(publicActionsL2()) + .extend(walletActionsL2()) + +const wallet1 = createWalletClient({ + chain: interopAlpha1, + transport: http(), + account +}).extend(publicActions) + .extend(publicActionsL2()) + .extend(walletActionsL2()) + +const token0 = getContract({ + address: tokenAddress, + abi: [balanceOf], + client: wallet0 +}) + +const token1 = getContract({ + address: tokenAddress, + abi: [balanceOf], + client: wallet1 +}) + + +const reportBalances = async () => { + const balance0 = await token0.read.balanceOf([account.address]) + const balance1 = await token1.read.balanceOf([account.address]) + + console.log(` +Address: ${account.address} + chain0: ${balance0.toString().padStart(20)} + chain1: ${balance1.toString().padStart(20)} + +`) +} + +await reportBalances() + +const sendTxnHash = await wallet0.interop.sendSuperchainERC20({ + tokenAddress, + to: account.address, + amount: 1000000000, + chainId: wallet1.chain.id +}) + +console.log(`Send transaction: https://sid.testnet.routescan.io/tx/${sendTxnHash}`) + +const sendTxnReceipt = await wallet0.waitForTransactionReceipt({ + hash: sendTxnHash +}) + +const sentMessage = + (await createInteropSentL2ToL2Messages(wallet0, { receipt: sendTxnReceipt })) + .sentMessages[0] + +const relayTxnHash = await wallet1.interop.relayMessage({ + sentMessageId: sentMessage.id, + sentMessagePayload: sentMessage.payload, +}) + +const relayTxnReceipt = await wallet1.waitForTransactionReceipt({ + hash: relayTxnHash +}) + +console.log(`Relay transaction: https://sid.testnet.routescan.io/tx/${relayTxnHash}`) + +await reportBalances() From 15bb644010c636aceda35c2c75bcefe33b84f979 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 19 Feb 2025 18:24:36 -0600 Subject: [PATCH 02/14] Added links to the UI, and a link from the explainer --- pages/stack/interop/superchain-erc20.mdx | 7 +++++++ pages/stack/interop/tutorials/transfer-superchainERC20.mdx | 4 +++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/pages/stack/interop/superchain-erc20.mdx b/pages/stack/interop/superchain-erc20.mdx index b120859b9..f85d6a0c6 100644 --- a/pages/stack/interop/superchain-erc20.mdx +++ b/pages/stack/interop/superchain-erc20.mdx @@ -13,6 +13,13 @@ Please note that the OP Stack interoperability upgrade, required for crosschain # SuperchainERC20 + + This tutorial provides a behind the scenes explanation of how `SuperchainERC20` tokens are transferred. + + - [See the tutorial](tutorials/transfer-superchainERC20) for how your application can transfer `SuperchainERC20` tokens. + - For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). + + The [`SuperchainERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol) contract implements [ERC-7802](https://ethereum-magicians.org/t/erc-7802-crosschain-token-interface/21508) to enable asset interoperability within the Superchain. Asset interoperability allows tokens to move securely across the Superchain by burning tokens on the source chain and minting an equivalent amount on the destination chain. This approach addresses issues such as liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools. diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 4aea1ccf6..dbd36e52f 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -17,7 +17,9 @@ This guide shows how to transfer `SuperchainERC20` tokens between chains program This tutorial provides step-by-step instructions for transferring `SuperchainERC20` tokens using code. - [See here](../superchain-erc20#how-it-works) for a detailed explanation of how this works. + + - For a detailed behind the scenes explanation, [see the explainer](../superchain-erc20#how-it-works). + - For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). ## Overview From 8b3122067b9f8bd80c162576d8294985364ef1c8 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 19 Feb 2025 18:36:04 -0600 Subject: [PATCH 03/14] lint --- pages/stack/interop/superchain-erc20.mdx | 12 ++-- .../tutorials/transfer-superchainERC20.mdx | 69 +++++++++---------- words.txt | 4 +- 3 files changed, 38 insertions(+), 47 deletions(-) diff --git a/pages/stack/interop/superchain-erc20.mdx b/pages/stack/interop/superchain-erc20.mdx index f85d6a0c6..2ff870760 100644 --- a/pages/stack/interop/superchain-erc20.mdx +++ b/pages/stack/interop/superchain-erc20.mdx @@ -7,17 +7,17 @@ description: Learn about the basic details of the SuperchainERC20 implementation import { Callout } from 'nextra/components' -The SuperchainERC20 standard is ready for production use with active Mainnet deployments. -Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development. + The SuperchainERC20 standard is ready for production use with active Mainnet deployments. + Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development. # SuperchainERC20 - This tutorial provides a behind the scenes explanation of how `SuperchainERC20` tokens are transferred. - - - [See the tutorial](tutorials/transfer-superchainERC20) for how your application can transfer `SuperchainERC20` tokens. - - For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). + This tutorial provides a behind the scenes explanation of how `SuperchainERC20` tokens are transferred. + + * [See the tutorial](tutorials/transfer-superchainERC20) for how your application can transfer `SuperchainERC20` tokens. + * For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). The [`SuperchainERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainERC20.sol) contract implements [ERC-7802](https://ethereum-magicians.org/t/erc-7802-crosschain-token-interface/21508) to enable asset interoperability within the Superchain. diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index dbd36e52f..0bd8da285 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -7,24 +7,24 @@ description: Learn how to transfer a SuperchainERC20 between chains using L2ToL2 import { Callout, Steps } from 'nextra/components' -The SuperchainERC20 standard is ready for production use with active Mainnet deployments. -Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development. + The SuperchainERC20 standard is ready for production use with active Mainnet deployments. + Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development. -# Transferring a SuperchainERC20 +# Transferring SuperchainERC20 tokens This guide shows how to transfer `SuperchainERC20` tokens between chains programatically. This tutorial provides step-by-step instructions for transferring `SuperchainERC20` tokens using code. - - - For a detailed behind the scenes explanation, [see the explainer](../superchain-erc20#how-it-works). - - For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). + + * For a detailed behind the scenes explanation, [see the explainer](../superchain-erc20#how-it-works). + * For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). ## Overview -**Warning:** Always verify your addresses and amounts before sending transactions. +**Warning:** Always verify your addresses and amounts before sending transactions. Cross-chain transfers cannot be reversed. ### What you'll build @@ -61,39 +61,37 @@ The tutorial uses these primary tools: * Node: For running TypeScript code from the command line * Viem: For blockchain interaction - ## Directions - ### Preparation You need onchain `SuperchainERC20` tokens. You can [deploy your own token](./deploy-superchain-erc20), but in this tutorial we will use [`CustomSuperchainToken`](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8), existing `SuperchainERC20` token on the [Interop devnet](../tools/devnet). - 1. Create environment variables for the RPC endpoints for the blockchains and the token address. + 1. Create environment variables for the RPC endpoints for the blockchains and the token address. ```sh RPC_DEV0=https://interop-alpha-0.optimism.io RPC_DEV1=https://interop-alpha-1.optimism.io TOKEN_ADDRESS=0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8 - ``` + ``` - 1. Set `PRIVATE_KEY` to the private key of an address that has [Sepolia ETH](https://cloud.google.com/application/web3/faucet/ethereum/sepolia). + 2. Set `PRIVATE_KEY` to the private key of an address that has [Sepolia ETH](https://cloud.google.com/application/web3/faucet/ethereum/sepolia). ```sh export PRIVATE_KEY=0x MY_ADDRESS=`cast wallet address $PRIVATE_KEY` ``` - 1. Send ETH to the two L2 blockchains. + 3. Send ETH to the two L2 blockchains. ```sh cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIVATE_KEY --value 0.02ether 0x7385d89d38ab79984e7c84fab9ce5e6f4815468a cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIVATE_KEY --value 0.02ether 0x55f5c4653dbcde7d1254f9c690a5d761b315500c ``` - 1. Wait a few minutes until you can see the ETH [on the block explorer](https://sid.testnet.routescan.io/) for your address. + 4. Wait a few minutes until you can see the ETH [on the block explorer](https://sid.testnet.routescan.io/) for your address.
Sanity check @@ -104,27 +102,25 @@ The tutorial uses these primary tools: ```
- 1. Obtain tokens on Interop devnet 0. - When using `CustomSuperchainToken` there are two ways to do this: + 5. Obtain tokens on Interop devnet 0. + When using `CustomSuperchainToken` there are two ways to do this: - - Use the [block explorer](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000) and a browser wallet to run the [faucet](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000#F6) function. + * Use the [block explorer](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000) and a browser wallet to run the [faucet](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000#F6) function. - - Use `cast` to call the `faucet` function. + * Use `cast` to call the `faucet` function. - ```sh - cast send --rpc-url $RPC_DEV0 --private-key $PRIVATE_KEY $TOKEN_ADDRESS "faucet()" - ``` + ```sh + cast send --rpc-url $RPC_DEV0 --private-key $PRIVATE_KEY $TOKEN_ADDRESS "faucet()" + ```
+ Sanity check - Sanity check - - Run this command to check your token balance. - - ```sh - cast call --rpc-url $RPC_DEV0 $TOKEN_ADDRESS "balanceOf(address)" $MY_ADDRESS | cast --from-wei - ``` + Run this command to check your token balance. + ```sh + cast call --rpc-url $RPC_DEV0 $TOKEN_ADDRESS "balanceOf(address)" $MY_ADDRESS | cast --from-wei + ```
### Transfer tokens using TypeScript @@ -142,7 +138,7 @@ The tutorial uses these primary tools: mkdir src ``` - 1. Edit `package.json` to add the `start` script. + 2. Edit `package.json` to add the `start` script. ```json { @@ -167,13 +163,12 @@ The tutorial uses these primary tools: } ``` - 1. Create `src/xfer-erc20.mts`: + 3. Create `src/xfer-erc20.mts`: ```solidity file=/public/tutorials/xfer-erc20.mts hash=19a948eeb482046afb1a55ccc5019599 ```
- Explanation ```solidity file=/public/tutorials/xfer-erc20.mts#L79-L84 hash=85f317d0cbe2b59e303e36a3e6154c62 @@ -182,7 +177,7 @@ The tutorial uses these primary tools: Use `@eth-optimism/viem`'s `walletActionsL2().sendSuperchainERC20` to send the `SuperchainERC20` tokens. Internally, this function calls [`SuperchainTokenBridge.sendERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol#L52-L78) to send the tokens. - ```typescript file=/public/tutorials/xfer-erc20.mts#L88-L90 hash=cab6e961b558f4f5a7b877062b1cfa45 + ```typescript file=/public/tutorials/xfer-erc20.mts#L88-L90 hash=cab6e961b558f4f5a7b877062b1cfa45 ``` To relay a message we need the information in the receipt. @@ -198,15 +193,13 @@ The tutorial uses these primary tools: ``` This is how you use `@eth-optimism/viem` to create an executing message. -
- 1. Run the TypeScript program, and see the change in your `CustomSuperchainToken` balances. - - ```sh - npm start - ``` + 4. Run the TypeScript program, and see the change in your `CustomSuperchainToken` balances. + ```sh + npm start + ``` ## Next steps diff --git a/words.txt b/words.txt index f4402123e..37aaa2fdc 100644 --- a/words.txt +++ b/words.txt @@ -107,7 +107,6 @@ dripcheck Drippie Eigen EIPs -emmited ENABLEDEPRECATEDPERSONAL enabledeprecatedpersonal enginekind @@ -237,7 +236,6 @@ multichain multiclient multisigs MULTU -neccessary nethermind NETRESTRICT netrestrict @@ -316,6 +314,7 @@ PRICELIMIT pricelimit productionize productionized +programatically Protip Proxied Proxyd @@ -420,7 +419,6 @@ undercollateralize Unichain unmetered Unprotect -unqiue unsubmitted UPNP VERKLE From 0a1c8ec0ccef38790504f016b7aa8a605aa1305a Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Thu, 20 Feb 2025 10:47:34 -0600 Subject: [PATCH 04/14] lint and coderabbit --- .../stack/interop/tutorials/transfer-superchainERC20.mdx | 8 ++++---- words.txt | 1 - 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 0bd8da285..4d208b5b0 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -13,12 +13,12 @@ import { Callout, Steps } from 'nextra/components' # Transferring SuperchainERC20 tokens -This guide shows how to transfer `SuperchainERC20` tokens between chains programatically. +This guide shows how to transfer `SuperchainERC20` tokens between chains programmatically. This tutorial provides step-by-step instructions for transferring `SuperchainERC20` tokens using code. - * For a detailed behind the scenes explanation, [see the explainer](../superchain-erc20#how-it-works). + * For a detailed behind-the-scenes explanation, [see the explainer](../superchain-erc20#how-it-works). * For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). @@ -103,7 +103,7 @@ The tutorial uses these primary tools: 5. Obtain tokens on Interop devnet 0. - When using `CustomSuperchainToken` there are two ways to do this: + When using `CustomSuperchainToken`, there are two ways to do this: * Use the [block explorer](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000) and a browser wallet to run the [faucet](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8/contract/420120000/writeContract?chainid=420120000#F6) function. @@ -180,7 +180,7 @@ The tutorial uses these primary tools: ```typescript file=/public/tutorials/xfer-erc20.mts#L88-L90 hash=cab6e961b558f4f5a7b877062b1cfa45 ``` - To relay a message we need the information in the receipt. + To relay a message, we need the information in the receipt. Also, we need to wait until the transaction with the relayed message is actually part of a block. ```typescript file=/public/tutorials/xfer-erc20.mts#L92-L94 hash=1da0981adb2fbd38cccf1b0602158418 diff --git a/words.txt b/words.txt index 37aaa2fdc..3ee228103 100644 --- a/words.txt +++ b/words.txt @@ -314,7 +314,6 @@ PRICELIMIT pricelimit productionize productionized -programatically Protip Proxied Proxyd From 2b550290689cb6f178baa6e564fa9a0bc670fc57 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Thu, 20 Feb 2025 11:23:48 -0600 Subject: [PATCH 05/14] Update superchain-erc20.mdx --- pages/stack/interop/superchain-erc20.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/superchain-erc20.mdx b/pages/stack/interop/superchain-erc20.mdx index 2ff870760..e3208c6a5 100644 --- a/pages/stack/interop/superchain-erc20.mdx +++ b/pages/stack/interop/superchain-erc20.mdx @@ -7,7 +7,7 @@ description: Learn about the basic details of the SuperchainERC20 implementation import { Callout } from 'nextra/components' - The SuperchainERC20 standard is ready for production use with active Mainnet deployments. + The SuperchainERC20 standard is ready for production deployments. Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development. From bc2fbb522b2f1aa16f5e92a08814f26ea0262cda Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Thu, 20 Feb 2025 11:24:36 -0600 Subject: [PATCH 06/14] Update transfer-superchainERC20.mdx --- pages/stack/interop/tutorials/transfer-superchainERC20.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 4d208b5b0..b61c4bd40 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -7,7 +7,7 @@ description: Learn how to transfer a SuperchainERC20 between chains using L2ToL2 import { Callout, Steps } from 'nextra/components' - The SuperchainERC20 standard is ready for production use with active Mainnet deployments. + The SuperchainERC20 standard is ready for production deployments. Please note that the OP Stack interoperability upgrade, required for crosschain messaging, is currently still in active development. From 8a6e9ae61f3dabf9f1b4cd6b9f2288e6dfe9003e Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Thu, 20 Feb 2025 15:46:08 -0600 Subject: [PATCH 07/14] Coderabbit --- pages/stack/interop/tutorials/transfer-superchainERC20.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index b61c4bd40..1ad27ad69 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -165,13 +165,13 @@ The tutorial uses these primary tools: 3. Create `src/xfer-erc20.mts`: - ```solidity file=/public/tutorials/xfer-erc20.mts hash=19a948eeb482046afb1a55ccc5019599 + ```typescript file=/public/tutorials/xfer-erc20.mts hash=19a948eeb482046afb1a55ccc5019599 ```
Explanation - ```solidity file=/public/tutorials/xfer-erc20.mts#L79-L84 hash=85f317d0cbe2b59e303e36a3e6154c62 + ```typescript file=/public/tutorials/xfer-erc20.mts#L79-L84 hash=85f317d0cbe2b59e303e36a3e6154c62 ``` Use `@eth-optimism/viem`'s `walletActionsL2().sendSuperchainERC20` to send the `SuperchainERC20` tokens. From 3cdbb8ded390d36a9993e8617289e9f216338ebc Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Fri, 21 Feb 2025 18:26:43 -0600 Subject: [PATCH 08/14] Put warning in a callout as per @sbvegan --- .../interop/tutorials/transfer-superchainERC20.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 1ad27ad69..b61a610f1 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -15,17 +15,17 @@ import { Callout, Steps } from 'nextra/components' This guide shows how to transfer `SuperchainERC20` tokens between chains programmatically. - - This tutorial provides step-by-step instructions for transferring `SuperchainERC20` tokens using code. +Note that this tutorial provides step-by-step instructions for transferring `SuperchainERC20` tokens using code. - * For a detailed behind-the-scenes explanation, [see the explainer](../superchain-erc20#how-it-works). - * For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). - +* For a detailed behind-the-scenes explanation, [see the explainer](../superchain-erc20#how-it-works). +* For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). ## Overview -**Warning:** Always verify your addresses and amounts before sending transactions. -Cross-chain transfers cannot be reversed. + + Always verify your addresses and amounts before sending transactions. + Cross-chain transfers cannot be reversed. + ### What you'll build From 821a43a020df0d2e74b9037a0fc9003dffdd5453 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 24 Feb 2025 11:59:10 -0600 Subject: [PATCH 09/14] Autorelay --- pages/stack/interop/tutorials/transfer-superchainERC20.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index b61a610f1..264a36de5 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -5,6 +5,7 @@ description: Learn how to transfer a SuperchainERC20 between chains using L2ToL2 --- import { Callout, Steps } from 'nextra/components' +import { AutorelayCallout } from '@/components/AutorelayCallout' The SuperchainERC20 standard is ready for production deployments. @@ -177,6 +178,8 @@ The tutorial uses these primary tools: Use `@eth-optimism/viem`'s `walletActionsL2().sendSuperchainERC20` to send the `SuperchainERC20` tokens. Internally, this function calls [`SuperchainTokenBridge.sendERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol#L52-L78) to send the tokens. + + ```typescript file=/public/tutorials/xfer-erc20.mts#L88-L90 hash=cab6e961b558f4f5a7b877062b1cfa45 ``` From 07abc77fb9e7592219954ed4a645ba2a60645a5a Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Mon, 24 Feb 2025 16:21:03 -0600 Subject: [PATCH 10/14] More autorelay stuff --- components/AutorelayCallout.tsx | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 components/AutorelayCallout.tsx diff --git a/components/AutorelayCallout.tsx b/components/AutorelayCallout.tsx new file mode 100644 index 000000000..47c289c91 --- /dev/null +++ b/components/AutorelayCallout.tsx @@ -0,0 +1,27 @@ +/** + * The AutorelayCallout function renders a callout component with a message about autorelays + * + * @param {Props} props - Expected to be empty, ignored. + * @returns {ReactElement} The AutorelayCallout component, a callout that explains about autorelays. + */ +import type { ReactElement } from 'react'; +import { useState } from 'react'; + +interface Props { + context?: string; +} +export function AutorelayCallout({ context }: Props): ReactElement { + return ( +
+
+
+ Normally we expect Superchain blockchains to run an autorelayer and relay your messages automatically. + However, for performance reasons or reliability, you might decide to submit the executing message manually. + See below to learn how to do that. +
+
+
+ ); +} From c2e4515172a392abb30a923c3cf409fbb3ade707 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Wed, 5 Mar 2025 08:38:09 -0600 Subject: [PATCH 11/14] coderabbit --- components/AutorelayCallout.tsx | 22 ++++++++----------- .../tutorials/transfer-superchainERC20.mdx | 2 +- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/components/AutorelayCallout.tsx b/components/AutorelayCallout.tsx index 47c289c91..383b645d4 100644 --- a/components/AutorelayCallout.tsx +++ b/components/AutorelayCallout.tsx @@ -5,23 +5,19 @@ * @returns {ReactElement} The AutorelayCallout component, a callout that explains about autorelays. */ import type { ReactElement } from 'react'; -import { useState } from 'react'; +import { Callout } from 'nextra/components' -interface Props { - context?: string; -} -export function AutorelayCallout({ context }: Props): ReactElement { +// nx-w-full nx-flex nx-mt-6 +// nx-mt-6 nx-justify-center nx-items-center nx-bg-white dark:nx-bg-black" + +// import { Callout } from 'vocs/components' + +export function AutorelayCallout(): ReactElement { return ( -
-
-
+ Normally we expect Superchain blockchains to run an autorelayer and relay your messages automatically. However, for performance reasons or reliability, you might decide to submit the executing message manually. See below to learn how to do that. -
-
-
+ ); } diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 264a36de5..2fa90979c 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -153,7 +153,7 @@ The tutorial uses these primary tools: "keywords": [], "author": "", "license": "ISC", - "type": "commonjs", + "type": "module", "description": "", "devDependencies": { "@eth-optimism/viem": "^0.3.2", From 8510c017d76f41c8099d5d9bdca93385ddb7111b Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Thu, 6 Mar 2025 09:27:58 -0600 Subject: [PATCH 12/14] @bradleycamacho comments --- pages/stack/interop/tutorials/transfer-superchainERC20.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 2fa90979c..9f895fd41 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -97,6 +97,8 @@ The tutorial uses these primary tools:
Sanity check + Check the ETH balance of your address on both blockchains. + ```sh cast balance --ether $MY_ADDRESS --rpc-url $RPC_DEV0 cast balance --ether $MY_ADDRESS --rpc-url $RPC_DEV1 @@ -127,7 +129,7 @@ The tutorial uses these primary tools: ### Transfer tokens using TypeScript We are going to use a [Node](https://nodejs.org/en) project, to be able to use [`@eth-optimism/viem`](https://www.npmjs.com/package/@eth-optimism/viem) to send the executing message. - We use [TypeScript](https://www.typescriptlang.org/) to have type safety combined with JavaScript functionality. + We use [TypeScript](https://www.typescriptlang.org/) to have [type safety](https://en.wikipedia.org/wiki/Type_safety) combined with JavaScript functionality. 1. Initialize a new Node project. @@ -170,7 +172,7 @@ The tutorial uses these primary tools: ```
- Explanation + Explanation of `xfer-erc20.mts` ```typescript file=/public/tutorials/xfer-erc20.mts#L79-L84 hash=85f317d0cbe2b59e303e36a3e6154c62 ``` From 9e8b5eaaedfa14f2e2c71042886c88036a7381a5 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Thu, 6 Mar 2025 09:40:26 -0600 Subject: [PATCH 13/14] fix links --- pages/stack/interop/tutorials/transfer-superchainERC20.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 9f895fd41..c2715f180 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -18,7 +18,7 @@ This guide shows how to transfer `SuperchainERC20` tokens between chains program Note that this tutorial provides step-by-step instructions for transferring `SuperchainERC20` tokens using code. -* For a detailed behind-the-scenes explanation, [see the explainer](../superchain-erc20#how-it-works). +* For a detailed behind-the-scenes explanation, [see the explainer](/stack/interop/superchain-erc20#how-it-works). * For a sample UI that bridges a `SuperchainERC20` token, [see here](https://interop-alpha-app.superchain.tools/). ## Overview @@ -68,7 +68,7 @@ The tutorial uses these primary tools: ### Preparation You need onchain `SuperchainERC20` tokens. - You can [deploy your own token](./deploy-superchain-erc20), but in this tutorial we will use [`CustomSuperchainToken`](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8), existing `SuperchainERC20` token on the [Interop devnet](../tools/devnet). + You can [deploy your own token](./deploy-superchain-erc20), but in this tutorial we will use [`CustomSuperchainToken`](https://sid.testnet.routescan.io/address/0xF3Ce0794cB4Ef75A902e07e5D2b75E4D71495ee8), existing `SuperchainERC20` token on the [Interop devnet](/stack/interop/tools/devnet). 1. Create environment variables for the RPC endpoints for the blockchains and the token address. From e9ddbd8ccce9a1411570103aa1d03bcfc5597af5 Mon Sep 17 00:00:00 2001 From: Bradley Camacho <42678939+bradleycamacho@users.noreply.github.com> Date: Fri, 7 Mar 2025 12:02:33 -0800 Subject: [PATCH 14/14] Remove extra description --- pages/stack/interop/tutorials/transfer-superchainERC20.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx index 4cc901bad..c2715f180 100644 --- a/pages/stack/interop/tutorials/transfer-superchainERC20.mdx +++ b/pages/stack/interop/tutorials/transfer-superchainERC20.mdx @@ -1,8 +1,5 @@ --- title: Transferring SuperchainERC20 tokens -description: >- - Learn how to transfer a SuperchainERC20 between chains using - L2ToL2CrossDomainMessenger. lang: en-US description: Learn how to transfer a SuperchainERC20 between chains using L2ToL2CrossDomainMessenger. ---