<AppchainBridge /> · OnchainKit

Bridge to appchains with OnchainKit

⚠️ NOTE

The AppchainBridge component is alpha release software and is provided AS-IS. Use at your own risk.

The AppchainBridge component provides a simple interface for implementing bridging to appchains with OnchainKit.

Prerequisites

Before using the AppchainBridge component, ensure you’ve completed the Getting Started steps.

Starting a new project

If you’re starting a new project, we recommend using create onchain to scaffold your project.

npm create onchain@latest

Adding to an existing project

If you’re adding AppchainBridge to an existing project, simply install OnchainKit.

npm

npm install @coinbase/onchainkit

Wrap the <OnchainKitProvider /> around your app, following the steps in Getting Started.

Quickstart

To use AppchainBridge, you’ll need to create a custom chain for your network using Viem’s defineChain.

You can retrieve the chain ID and your RPC URL from your appchain’s dashboard in Coinbase Developer Platform.

Once successfully created, add the custom chain to your Wagmi configuration, and provide it as a child component to OnchainKitProvider.

chain.ts

// @noErrors: 2554
import { defineChain } from 'viem';

export const EXAMPLE_CHAIN = defineChain({
  id: 8453200000, 
  name: 'Your Appchain Network',
  nativeCurrency: {
    name: 'Ethereum',
    symbol: 'ETH',
    decimals: 18,
  },
  rpcUrls: {
    default: {
      http: ['https://your-rpc.appchain.base.org'], 
    },
  },
});

Use the custom chain to create an Appchain object. You can also render an icon in the UI using the icon prop.

// @noErrors: 2554
import { defineChain } from 'viem';
const EXAMPLE_CHAIN = defineChain({
  id: 8453200000, 
  name: 'Your Appchain Network',
  nativeCurrency: {
    name: 'Ethereum',
    symbol: 'ETH',
    decimals: 18,
  },
  rpcUrls: {
    default: {
      http: ['https://your-rpc.appchain.base.org'], 
    },
  },
});
// ---cut-before---
import type { Appchain } from '@coinbase/onchainkit/appchain';

const EXAMPLE_APPCHAIN: Appchain = {
  chain: EXAMPLE_CHAIN,
<Frame>
  icon: <img src="https://some-icon.com/icon.png" alt="Your Appchain Network" />,
</Frame>
};

Now, you can render the AppchainBridge component with the chain and appchain props.

// @noErrors: 2554
import { defineChain } from 'viem';
const EXAMPLE_CHAIN = defineChain({
  id: 8453200000, 
  name: 'Your Appchain Network',
  nativeCurrency: {
    name: 'Ethereum',
    symbol: 'ETH',
    decimals: 18,
  },
  rpcUrls: {
    default: {
      http: ['https://your-rpc.appchain.base.org'], 
    },
  },
});
import type { Appchain } from '@coinbase/onchainkit/appchain';

const EXAMPLE_APPCHAIN: Appchain = {
  chain: EXAMPLE_CHAIN,
<Frame>
  icon: <img src="https://some-icon.com/icon.png" alt="Your Appchain Network" />,
</Frame>
};
// ---cut-before---
import { AppchainBridge } from '@coinbase/onchainkit/appchain';
import { baseSepolia } from 'viem/chains';

<AppchainBridge chain={baseSepolia} appchain={EXAMPLE_APPCHAIN} />

Custom bridgeable tokens

By default, the bridgeable token is only native ETH. You can customize the bridgeable tokens by providing a bridgeableTokens prop to the AppchainBridge component.

Let’s add a custom “Appchain Token” to the bridgeable tokens array.

// @noErrors: 2554
import { defineChain } from 'viem';
const EXAMPLE_CHAIN = defineChain({
  id: 8453200000, 
  name: 'Your Appchain Network',
  nativeCurrency: {
    name: 'Ethereum',
    symbol: 'ETH',
    decimals: 18,
  },
  rpcUrls: {
    default: {
      http: ['https://your-rpc.appchain.base.org'], 
    },
  },
});
import type { Appchain } from '@coinbase/onchainkit/appchain';

const EXAMPLE_APPCHAIN: Appchain = {
  chain: EXAMPLE_CHAIN,
<Frame>
  icon: <img src="https://some-icon.com/icon.png" alt="Your Appchain Network" />,
</Frame>
};
// ---cut-before---
import type { BridgeableToken } from '@coinbase/onchainkit/appchain';

const customBridgeableTokens: BridgeableToken[] = [
  {
    name: 'ETH',
    address: '',
    symbol: 'ETH',
    decimals: 18,
    image:
    'https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png',
    chainId: 8453200000,
  },
  {
    address: '0x...',
    remoteToken: '0x...',
    name: 'Appchain Token',
    symbol: 'ATKN',
    decimals: 18,
    chainId: 8453200000,
    image: 'https://some-icon.com/icon.png',
  },
];

⚠️ What is remoteToken?

The remoteToken field represents the token address on the appchain you’re bridging to.

ERC-20 tokens on the appchain must comply to the IOptimismMintableERC20 interface to be bridgeable.

Follow the Optimism documentation to retrieve the remoteToken address for your ERC-20 token.

You can then plug the customBridgeableTokens into the AppchainBridge component with the bridgeableTokens prop.

// @noErrors: 2554
// @noErrors: 2304
import type { BridgeableToken } from '@coinbase/onchainkit/appchain';

const customBridgeableTokens: BridgeableToken[] = [
  {
    name: 'ETH',
    address: '',
    symbol: 'ETH',
    decimals: 18,
    image:
    'https://wallet-api-production.s3.amazonaws.com/uploads/tokens/eth_288.png',
    chainId: 84532,
  },
  {
    address: '0x...',
    remoteToken: '0x...',
    name: 'Sandbox Token',
    symbol: 'SBOX',
    decimals: 18,
    chainId: 8453200058,
    image: 'https://img.cryptorank.io/coins/blocklords1670492311588.png',
  },
];
// ---cut-before---
import { AppchainBridge } from '@coinbase/onchainkit/appchain';
import { baseSepolia } from 'viem/chains';

<AppchainBridge
  chain={baseSepolia}
  appchain={SANDBOX_APPCHAIN}
  bridgeableTokens={customBridgeableTokens}
/>

Chains with custom gas tokens

For chains that use custom gas tokens, simply set the isCustomGasToken field to true on the custom gas token for your bridgeable token.

// @noErrors: 2554
import type { BridgeableToken } from '@coinbase/onchainkit/appchain';

const customGasToken: BridgeableToken[] = [
  {
    address: '0x...',
    remoteToken: '0x...',
    name: 'Appchain Token',
    symbol: 'ATKN',
    decimals: 18,
    chainId: 8453200000,
    image: 'https://some-icon.com/icon.png',
    isCustomGasToken: true, 
  },
];

Fetching price for custom tokens

By default, we provide a price feed for ETH and USDC.

To fetch the price of custom ERC-20 tokens, you can override the handleFetchPrice function in the AppchainBridge component. This callback is run everytime the user changes the input amount.

The function must match the following signature:

(amount: string, token: Token) => Promise<string>;

// @noErrors: 2554
// @noErrors: 2362 2363 2304
import { AppchainBridge } from '@coinbase/onchainkit/appchain';
import { baseSepolia } from 'viem/chains';

const handleFetchPrice = async (amount: string, token: Token) => {
  // Example of fetching price
  const price = await fetch(`https://api.example.com/price/${token.address}`);
  return price * amount;
};

<AppchainBridge
  chain={baseSepolia}
  appchain={EXAMPLE_APPCHAIN}
  bridgeableTokens={customBridgeableTokens}
  handleFetchPrice={handleFetchPrice}
/>

Components

The AppchainBridge component includes the following subcomponents:

• <AppchainBridge /> - A fully built bridge component that handles deposits and withdrawals. Also includes a children prop to render custom components.
• <AppchainBridgeProvider /> - A headless provider that provides the bridge context to child components.
• <AppchainBridgeInput /> - A component that handles the amount input for bridging tokens.
• <AppchainBridgeNetwork /> - A component that displays network information and allows network selection.
• <AppchainBridgeTransactionButton /> - A component that triggers bridge transactions.
• <AppchainBridgeWithdraw /> - A component that handles the withdrawal interface.
• <AppchainNetworkToggleButton /> - A button component for toggling between networks.
• <AppchainBridgeSuccess /> - A component that displays transaction success states.
• <AppchainBridgeResumeTransaction /> - A component that handles resuming interrupted bridge transactions.

Props

• Appchain
• AppchainBridgeReact
• AppchainBridgeProviderReact
• AppchainBridgeContextType
• BridgeableToken
• ChainWithIcon
• AppchainConfig
• AppchainBridgeSuccessReact
• BridgeParams
• ChainConfigParams
• UseDepositParams
• UseWithdrawParams
• UseDepositButtonParams
• UseWithdrawButtonParams