Bridging ERC-20 Token

Bridge ERC-20 tokens from Ethereum to GIWA, and from GIWA to Ethereum.

Requirements

Make sure the following are installed.

• node

• pnpm

Set up development environment

In this tutorial, we’ll use viem. Viem is a Node.js library, so we’ll start by creating a Node.js project.

1

Create a project folder

mkdir giwa-bridging-erc20
cd giwa-bridging-erc20

2

Initialize the project

pnpm init

3

Install dependencies

pnpm add -D tsx @types/node
pnpm add viem@^2.38.0

Prepare a wallet

You’ll need a wallet to bridge an ERC-20 token.

1

Get Sepolia ETH

You’ll need ETH on both Ethereum Sepolia and GIWA Sepolia to bridge tokens.

• Ethereum Sepolia Faucet

• GIWA Sepolia Faucet

Don’t have a wallet yet? Use cast command to create one.

2

Set the Private Key environment variable

This tutorial requires multiple transaction signatures. To handle this, you’ll need to set your wallet private key as an environment variable.

export TEST_PRIVATE_KEY=0x...

Configure the Chain Client

Set up chain client for ERC-20 bridging.

src/config.ts

import {defineChain, createPublicClient, http, createWalletClient} from "viem";
import {privateKeyToAccount} from "viem/accounts";
import {publicActionsL1, publicActionsL2, walletActionsL1, walletActionsL2} from "viem/op-stack";
import {sepolia, giwaSepolia} from "viem/chains";

// Prepare wallet
export const PRIVATE_KEY = process.env.TEST_PRIVATE_KEY as `0x${string}`;
export const account = privateKeyToAccount(PRIVATE_KEY);

// Client for reading Ethereum Sepolia chain data
export const publicClientL1 = createPublicClient({
  chain: sepolia,
  transport: http(),
}).extend(publicActionsL1())

// Client for sending transactions on Ethereum Sepolia
export const walletClientL1 = createWalletClient({
  account,
  chain: sepolia,
  transport: http(),
}).extend(walletActionsL1());

// Client for reading GIWA Sepolia chain data
export const publicClientL2 = createPublicClient({
  chain: giwaSepolia,
  transport: http(),
}).extend(publicActionsL2());

// Client for sending transactions on GIWA Sepolia
export const walletClientL2 = createWalletClient({
  account,
  chain: giwaSepolia,
  transport: http(),
}).extend(walletActionsL2());

Set contract addresses and ABIs

We’ve deployed a test ERC-20 on Ethereum and GIWA for bridging. The L2 token below is the bridged version of the L1 token.

• L1 Token

• L2 Token

Bridging ERC-20 token can be done using L1StandardBridge contract. Let's define ABIs for required functions.

What is an ABI?

An ABI (Application Binary Interface) is the interface required to interact with a smart contract. It defines the contract’s function names, parameters, and return values. Clients, SDKs, and other tools use the ABI to make calls to the contract.

src/contract.ts

import {giwaSepolia} from "./config";
import {erc20Abi, parseAbi} from "viem";
import {sepolia} from "viem/chains";

// Contract addresses for ERC-20 bridging
export const l1TokenAddress = '0x50B1eF6e0fe05a32F3E63F02f3c0151BD9004C7c';
export const l2TokenAddress = '0xB11E5c9070a57C0c33Df102436C440a2c73a4c38';
export const l1StandardBridgeAddress = giwaSepolia.contracts.l1StandardBridge[sepolia.id].address;
export const l2StandardBridgeAddress = giwaSepolia.contracts.l2StandardBridge.address;

// ABIs for the ERC-20 token, L1StandardBridge and L2StandardBridge
export const testTokenAbi = [
  ...erc20Abi,
  ...parseAbi([
    'function claimFaucet() external'
  ]),
];
export const l1StandardBridgeAbi = parseAbi([
  'function depositERC20To(address _l1Token, address _l2Token, address _to, uint256 _amount, uint32 _minGasLimit, bytes calldata _extraData) external'
]);
export const l2StandardBridgeAbi = parseAbi([
  'function withdrawTo(address _l2Token, address _to, uint256 _amount, uint32 _minGasLimit, bytes calldata _extraData) external'
])

Get L1 faucet tokens

To make a deposit (Ethereum -> GIWA), you’ll need faucet tokens on the Ethereum Sepolia network. The L1 token defined above includes a claimFaucet function. Run the code below to call claimFaucet and receive your L1 faucet tokens.

1

Writing the code

src/get_l1_token.ts

import {walletClientL1, account} from "./config";
import {l1TokenAddress, testTokenAbi } from "./contract";

async function main() {
  console.log('Getting tokens from faucet...');
  const claimHash = await walletClientL1.writeContract({
    address: l1TokenAddress,
    abi: testTokenAbi,
    functionName: 'claimFaucet',
    account,
  });
  console.log(`Claim Faucet transaction hash on L1: ${claimHash}`);
  
  const claimReceipt = await publicClientL1.waitForTransactionReceipt({ hash: claimHash });
  console.log('L1 transaction confirmed:', claimReceipt);
}

main().then();

2

Running

node --import=tsx src/get_l1_token.ts

Deposit ERC-20 Token (Ethereum -> GIWA)

Now let’s bridge the faucet tokens from Ethereum to GIWA.

When you run the code below, your faucet tokens on Ethereum will actually be sent to the L1StandardBridge contract, and the same amount will be credited to your GIWA wallet. This process is called Lock-and-Mint .

1

Flow

1. Grant approval to L1StandardBridge contract so that it can transfer your ERC-20 tokens

2. Send the deposit transaction on L1

3. The corresponding L2 deposit transaction is created by the sequencer

4. Deposit complete

2

Writing the code

src/deposit_erc20.ts

import {
  account,
  publicClientL1,
  walletClientL1
} from "./config";
import {
  l1StandardBridgeAbi,
  l1StandardBridgeAddress,
  l1TokenAddress, l2TokenAddress,
  testTokenAbi
} from "./contract";
import {formatEther, parseUnits} from "viem";
import {getL2TransactionHashes} from "viem/op-stack";

async function main() {
  // Before bridging to GIWA, check your L1 ERC-20 token balance.
  const l1TokenBalance = await publicClientL1.readContract({
    address: l1TokenAddress,
    abi: testTokenAbi,
    functionName: 'balanceOf',
    args: [account.address],
  });
  console.log(`L1 Token Balance: ${formatUnits(l1TokenBalance, 18)} FAUCET`);

  // During bridging, your ERC-20 tokens must be transferred to the L1StandardBridge contract.
  // This is not a direct transfer by you; it happens internally when L1StandardBridge functions execute.
  // First call approve to grant transfer permission to the L1StandardBridge contract.
  const approveHash = await walletClientL1.writeContract({
    address: l1TokenAddress,
    abi: testTokenAbi,
    functionName: 'approve',
    args: [l1StandardBridgeAddress, parseUnits('1', 18)],
  });
  console.log(`Approve transaction hash on L1: ${approveHash}`);

  // Wait until the L1 transaction above is fully processed.
  const approveReceipt = await publicClientL1.waitForTransactionReceipt({ hash: approveHash });
  console.log('L1 transaction confirmed:', approveReceipt);

  // Send the deposit transaction on L1.
  // In this process, your ERC-20 tokens are sent to the L1StandardBridge contract.
  const depositHash = await walletClientL1.writeContract({
    address: l1StandardBridgeAddress,
    abi: l1StandardBridgeAbi,
    functionName: 'depositERC20To',
    args: [
      l1TokenAddress,
      l2TokenAddress,
      account.address,
      parseUnits('1', 18),
      200000,
      '0x',
    ],
  });
  console.log(`Deposit transaction hash on L1: ${depositHash}`);

  // Wait until the L1 transaction above is fully processed.
  const depositReceipt = await publicClientL1.waitForTransactionReceipt({ hash: depositHash });
  console.log('L1 transaction confirmed:', depositReceipt);

  // From the L1 receipt, precompute the L2 deposit transaction hash.
  const [l2Hash] = getL2TransactionHashes(depositReceipt);
  console.log(`Corresponding L2 transaction hash: ${l2Hash}`);
  
  // Wait until the L2 deposit transaction above is processed.
  // This takes roughly 1–3 minutes.
  const l2Receipt = await publicClientL2.waitForTransactionReceipt({
    hash: l2Hash,
  });
  console.log('L2 transaction confirmed:', l2Receipt);
  console.log('Deposit completed successfully!');
}

main().then();

3

Running

node --import=tsx src/deposit_erc20.ts

Withdraw ERC-20 Token (GIWA -> Ethereum)

Have you successfully sent ERC-20 from Ethereum to GIWA? Now let’s bridge it back in the opposite direction — from GIWA to Ethereum.

When you run the code below, your ERC-20 tokens on GIWA are burned, and the same amount is released to your Ethereum wallet. In this case, the tokens locked in the L1StandardBridge contract during the Deposit are now unlocked. This process is called Burn-and-Unlock.

1

Flow

1. Send the withdrawal initiation transaction on L2

2. Send the withdrawal prove transaction on L1

3. Send the withdrawal finalize transaction on L1

4. Withdrawal complete

2

Writing the code

src/withdraw_erc20.ts

import {account, publicClientL1, walletClientL1, publicClientL2, walletClientL2} from "./config";
import {l2StandardBridgeAbi, l2StandardBridgeAddress, l2TokenAddress, testTokenAbi} from "./contract";
import {formatUnits, parseUnits} from "viem";

async function main() {
  // Before bridging back to Ethereum, check your L2 ERC-20 token balance.
  const l2TokenBalance = await publicClientL2.readContract({
    address: l2TokenAddress,
    abi: testTokenAbi,
    functionName: 'balanceOf',
    args: [account.address],
  });
  console.log(`L2 Token Balance: ${formatUnits(l2TokenBalance, 18)} FAUCET`);

  // Send the withdrawal transaction on L2.
  // In this process, your ERC-20 tokens are burned.
  const withdrawalHash = await walletClientL2.writeContract({
    address: l2StandardBridgeAddress,
    abi: l2StandardBridgeAbi,
    functionName: 'withdrawTo',
    args: [
      l2TokenAddress,
      account.address,
      parseUnits('0.5', 18),
      200000,
      '0x',
    ],
  });
  console.log(`Withdrawal transaction hash on L2: ${withdrawalHash}`);

  // Wait until the L2 transaction above is fully processed.
  const withdrawalReceipt = await publicClientL2.waitForTransactionReceipt({ hash: withdrawalHash });
  console.log('L2 transaction confirmed:', withdrawalReceipt);

  // Wait until the L2 withdrawal can be proven on L1.
  // This can take up to 2 hours.
  const { output, withdrawal } = await publicClientL1.waitToProve({
    receipt: withdrawalReceipt,
    targetChain: walletClientL2.chain
  });

  // Build parameters to send the prove transaction on L1.
  const proveArgs = await publicClientL2.buildProveWithdrawal({
    output,
    withdrawal,
  });

  // Prove the withdrawal on L1.
  const proveHash = await walletClientL1.proveWithdrawal(proveArgs);
  console.log(`Prove transaction hash on L1: ${proveHash}`);

  // Wait until the L1 transaction above is fully processed.
  const proveReceipt = await publicClientL1.waitForTransactionReceipt({ hash: proveHash });
  console.log('Prove transaction confirmed:', proveReceipt);

  // Wait until the withdrawal can be finalized.
  // This period is called the challenge period and takes about 7 days.
  await publicClientL1.waitToFinalize({
    targetChain: walletClientL2.chain,
    withdrawalHash: withdrawal.withdrawalHash,
  });

  // Finalize the withdrawal on L1.
  const finalizeHash = await walletClientL1.finalizeWithdrawal({
    targetChain: walletClientL2.chain,
    withdrawal,
  });
  console.log(`Finalize transaction hash on L1: ${finalizeHash}`);

  // Wait until the L1 transaction above is fully processed.
  const finalizeReceipt = await publicClientL1.waitForTransactionReceipt({
    hash: finalizeHash
  });
  console.log('Finalize transaction confirmed:', finalizeReceipt);

  // Read withdrawal status on L1.
  // Withdrawals take a long time to complete, so you can query status with this when needed.
  const status = await publicClientL1.getWithdrawalStatus({
    receipt: withdrawalReceipt,
    targetChain: walletClientL2.chain,
  });
  console.log('Withdrawal completed successfully!');
}

main().then();

3

Running

node --import=tsx src/withdraw_erc20.ts

Learn more

Interested in bridging data in addition to assets like ETH and ERC-20 tokens? Read the OP Stack docs and build your own implementation.