diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/advanced-configurations/04-layer-leap.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced-configurations/04-layer-leap.mdx new file mode 100644 index 000000000..5081738a9 --- /dev/null +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/advanced-configurations/04-layer-leap.mdx @@ -0,0 +1,133 @@ +--- +title: 'Integrate with Layer Leap' +description: 'Learn how to implement Layer Leap to enable direct token bridging from Ethereum to Arbitrum chain (Orbit)s' +author: leerderek +sme: amarrazza +target_audience: 'Developers who want to implement Layer Leap on their Arbitrum chain (Orbit)' +sidebar_position: 1 +--- + +## Overview + +Layer Leap is a protocol that enables users to bridge `ETH` and `ERC-20` tokens directly from Ethereum to Arbitrum chains (Orbit) in a single transaction. This significantly improves user experience by eliminating the need for intermediate bridging steps. + +### Key benefits + +- **For users**: Bridge tokens from Ethereum to any Arbitrum chain (Orbit) with a single transaction +- **For developers**: Seamlessly onboard users to your Arbitrum chain (Orbit) directly from Ethereum + +## How it works + +Layer Leap uses a [system of contracts](https://github.com/OffchainLabs/l1-l3-teleport-contracts) to coordinate token transfers across multiple layers: + +1. **L1Teleporter** (on Ethereum): Entry point for token transfers +2. **L2ForwarderFactory** (on Arbitrum One/Nova): Creates deterministic `L2Forwarder` contracts +3. **L2Forwarder** (on Arbitrum One/Nova): Handles the final transfer to the Arbitrum chain (Orbit) + +### Technical architecture + +Layer Leap leverages two key mechanisms: + +1. **For `ERC-20` tokens**: The Teleport Contracts coordinate transfers through the canonical token bridges of both the parent chain and the Arbitrum chain (Orbit) +2. **For `ETH`**: A "double retryable" approach, where a retryable ticket creates another retryable ticket to complete the cross-chain transfer + +## Requirements + +Layer Leap currently supports Arbitrum chain (Orbit)s with the following characteristics: + +- Built on top of an Arbitrum Layer 2 (Arbitrum One or Nova) +- Using `ETH` as the gas token +- The parent chain must be an Arbitrum chain (Orbit) due to reliance on retryable tickets. + +Support for Arbitrum chains (Orbit) with custom gas tokens is planned for future releases. + +## Implementation guide + +### Option 1: Integrate with Arbitrum bridge UI + +If you want your Arbitrum chain (Orbit) to appear on the Arbitrum bridge UI with Layer Leap support: + +1. If your chain is not yet on the Arbitrum bridge, submit a request using this [GitHub template](https://github.com/OffchainLabs/arbitrum-token-bridge/issues/new?assignees=&labels=feat%2Ctriage&projects=&template=add-orbit-chain-request.yml&title=%5Bfeat%5D%3A+) +2. Request Layer Leap activation using this [GitHub template](https://github.com/offchainlabs/arbitrum-token-bridge/issues/new?assignees=&labels=feat%2ctriage&projects=&template=add-layerleap-request.yml&title=%5bfeat%5d%3a+enable+layer+leap+for+%3corbit+chain%3e) + +### Option 2: Custom integration + +To integrate Layer Leap into your custom bridge UI: + +1. **Set up infrastructure** + + - Ensure your Arbitrum chain (Orbit) is properly configured + - Deploy and configure the necessary components + +2. **Implement the bridging flow** + + The simplest implementation uses the Arbitrum SDK: + +```typescript +import { TeleportTokenParameters, teleportToken } from '@arbitrum/sdk/dist/lib/teleport/teleport'; + +// Configure the token teleport parameters +const params: TeleportTokenParameters = { + l1Signer, // Ethereum signer + l2Provider, // Arbitrum L2 provider + l3Provider, // Arbitrum chain (Orbit) provider + erc20Address, // Token address (or null for ETH) + amount, // Amount to bridge + l3WalletAddress, // Recipient address on the Arbitrum chain (Orbit) + teleportType: TeleportType.STANDARD, // For ETH-fee chains +}; + +// Initiate the teleport +const result = await teleportToken(params); +console.log(`Teleport initiated with hash: ${result.hash}`); +``` + +3. **Monitor and track teleports** + + Track the status of a teleport: + +```typescript +import { TeleportStatus, getTeleportStatus } from '@arbitrum/sdk/dist/lib/teleport/status'; + +const status = await getTeleportStatus({ + l1Provider, + l2Provider, + l3Provider, + l1TxHash, +}); + +console.log(`Teleport status: ${TeleportStatus[status.status]}`); +``` + +## Best practices + +1. **Retryable monitoring** + + Run the [Retryables Monitoring tool](https://github.com/OffchainLabs/arb-retryables-monitoring) to track and redeem any failed retryables. + +2. **Gas estimation** + + Layer Leap requires sufficient gas to cover all steps across multiple chains. Conservative gas estimations are recommended. + +3. **Error handling** + + Implement proper error handling for each step of the teleport process, especially for handling potential failures at the L2 or L3 level. + +## Contract address + +| Contract | Address | +| ------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| Arb One/Nova L1Teleporter | [0xCBd9c6e310D6AaDeF9F025f716284162F0158992](https://etherscan.io/address/0xCBd9c6e310D6AaDeF9F025f716284162F0158992) | + +## Demo examples + +You can see Layer Leap in action on the Arbitrum Bridge by bridging to: + +- [Rari](https://bridge.arbitrum.io/?destinationChain=rari-mainnet&sourceChain=ethereum) +- [Proof of Play](https://bridge.arbitrum.io/?destinationChain=pop-apex&sourceChain=ethereum) + +## Resources + +- [Layer Leap repository](https://github.com/OffchainLabs/l1-l3-teleport-contracts) +- [SDK documentation](https://www.npmjs.com/package/@arbitrum/sdk/v/3.5.1-teleporter.0) +- [Request Layer Leap for your Arbitrum chain (Orbit)](https://github.com/OffchainLabs/arbitrum-token-bridge/issues/new?assignees=&labels=feat,triage&projects=&template=add-layerleap-request.yml&title=[feat]) diff --git a/sidebars.js b/sidebars.js index bb8717261..def8c3a12 100644 --- a/sidebars.js +++ b/sidebars.js @@ -379,6 +379,11 @@ const sidebars = { id: 'launch-arbitrum-chain/configure-your-chain/advanced-configurations/fast-withdrawals', label: `Enable fast withdrawals`, }, + { + type: 'doc', + label: 'Use Layer Leap', + id: 'launch-arbitrum-chain/configure-your-chain/advanced-configurations/layer-leap', + }, { type: 'category', label: 'Configure AEP fee routing', diff --git a/vercel.json b/vercel.json index ef638c7d7..e118816a8 100644 --- a/vercel.json +++ b/vercel.json @@ -570,11 +570,6 @@ "destination": "/(build-decentralized-apps/custom-gas-token-sdk/?)", "permanent": false }, - { - "source": "/(launch-arbitrum-chain/configure-your-chain/advanced-configurations/layer-leap/?)", - "destination": "/launch-arbitrum-chain/a-gentle-introduction", - "permanent": false - }, { "source": "/(launch-arbitrum-chain/deploy-an-arbitrum-chain/deploying-rollup-chain/?)", "destination": "/launch-arbitrum-chain/deploy-an-arbitrum-chain/deploying-an-arbitrum-chain",