From 3327bea7d82a8a9e7764c8c547e39f66df59d465 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mona=20B=C3=A4renf=C3=A4nger?= Date: Thu, 8 Aug 2024 12:48:39 +0200 Subject: [PATCH] Update token bridging guide (#188) * Update index page * Update sidebars * Improve structure * Update nav title * Update admonition * Update nav title * Remove admonition * Update footnote * Update section title * Add link * Update link * Align slug * Apply suggestions from code review Co-authored-by: Muhammad Talha <13951043+TalhaMaliktz@users.noreply.github.com> * Update link --------- Co-authored-by: Muhammad Talha <13951043+TalhaMaliktz@users.noreply.github.com> --- .../add-token-to-lisk/index.md | 86 ++++++++++++------- .../interacting-with-the-blockchain/viem.mdx | 2 +- sidebars.js | 8 +- 3 files changed, 58 insertions(+), 38 deletions(-) diff --git a/docs/building-on-lisk/add-token-to-lisk/index.md b/docs/building-on-lisk/add-token-to-lisk/index.md index 663a9122e..2b0a9a0fb 100644 --- a/docs/building-on-lisk/add-token-to-lisk/index.md +++ b/docs/building-on-lisk/add-token-to-lisk/index.md @@ -1,5 +1,5 @@ --- -title: Deploying an ERC-20 Token to Lisk +title: Introduction sidebar_position: 1 slug: /building-on-lisk/add-token-to-lisk description: 'Guide to adding external ERC-20 contracts deployed on Ethereum to Lisk network.' @@ -15,56 +15,80 @@ keywords: ] --- -# Deploying an ERC-20 Token to Lisk -This tutorial is meant for developers with an existing **Standard ERC-20** token or a **Custom ERC-20** token on Ethereum who want to deploy their respective token on Lisk. -In this guide, you'll learn how to deploy a Standard or a Custom ERC-20 token from Ethereum to Lisk. +# Bridging an L1 token to Lisk +This page is intended for token issuers who already have an ERC-20 contract deployed on Ethereum and would like to submit their token for bridging between Ethereum and Lisk. +Lisk uses the Superchain Token List as a reference for tokens that have been deployed on Lisk. -## About OptimismMintableERC20s +## Superchain Token List +The [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io) exists to help users discover the correct bridged token addresses for any given native token. -The Standard Bridge system requires that L2 representations of L1 tokens implement the [`IOptimismMintableERC20`](https://github.com/ethereum-optimism/optimism/blob/v1.1.4/packages/contracts-bedrock/src/universal/IOptimismMintableERC20.sol) interface. -This interface is a superset of the standard ERC-20 interface and includes functions that allow the bridge to properly verify deposits/withdrawals and mint/burn tokens as needed. -Your L2 token contract must implement this interface in order to be bridged using the Standard Bridge system. +Consider checking this list to make sure that you're not using the wrong bridged representation of a token when bridging a native token. + - +:::warning +Lisk does not endorse any of the tokens that are listed in the [**ethereum-optimism.github.io**](https://github.com/ethereum-optimism/ethereum-optimism.github.io) repository and relies on the preliminary checks put in place, listed on the repository. +::: - +## The Standard Bridge +Before a token native to one chain can be bridged to the other chain, a bridged representation of that token must be created on the receiving side. +The [Standard Bridge](https://docs.optimism.io/builders/app-developers/bridging/standard-bridge) allows users to convert tokens that are native to one chain (like Ethereum) into a representation of those tokens on the other chain (like Lisk). +Users can then convert these bridged representations back into their original native tokens at any time. - +A bridged representation of a token is an ERC-20 token that implements the `IOptimismMintableERC20`[^1] interface. +A native token may have more than one bridged representation at the same time. +Users must always specify which bridged token they wish to use when using the bridge; see [Superchain Token List](#superchain-token-list). +Different bridged representations of the same native token are considered entirely independent tokens. -## [Deploying a Standard ERC-20 token](./standard-token.md) +The Standard Bridge is a simple smart contract, with the functionality to move ERC-20 tokens between Lisk and Ethereum. -To deploy a Standard ERC-20 Token to Lisk or Lisk Sepolia network, follow the steps mentioned in the [Deploying Your Standard ERC-20 Token to Lisk](./standard-token.md) guide. +The protocol consists of two pertinent contracts: -The guide explains how to use the [OptimismMintableERC20Factory](https://github.com/ethereum-optimism/optimism/blob/186e46a47647a51a658e699e9ff047d39444c2de/packages/contracts-bedrock/contracts/universal/OptimismMintableERC20Factory.sol) to deploy a standardized ERC-20 token on Lisk or Lisk Sepolia network. -Tokens created by this factory contract implement the `IOptimismMintableERC20` interface, including basic logic for deposits, transfers, and withdrawals. +- A bridge contract deployed to **Ethereum**, called [L1StandardBridge](https://etherscan.io/address/0x2658723Bf70c7667De6B25F99fcce13A16D25d08). +- A bridge contract deployed to **Lisk**, called [L2StandardBridge](https://blockscout.lisk.com/address/0x4200000000000000000000000000000000000010). +These two contracts interact with one another via the `CrossDomainMessenger` system for sending messages between Ethereum and Lisk. +[^1]: The `IOptimismMintableERC20` interface is a superset of the [standard ERC-20 interface](https://eips.ethereum.org/EIPS/eip-20) and includes functions that allow the bridge to properly verify deposits/withdrawals and mint/burn tokens as needed. +All bridged versions of tokens must implement this interface in order to be bridged with the [Standard Bridge](#the-standard-bridge) system. +Native tokens do not need to implement this interface. -## [Deploying a Custom ERC-20 token](./custom-token.mdx) -A custom token allows you to do things like trigger extra logic whenever a token is deposited. -To deploy a custom ERC-20 token to Lisk or Lisk Sepolia network, follow the steps mentioned in the [Deploying your Custom ERC-20 token to Lisk](./custom-token.mdx) guide. +## Adding your token to the Superchain Token List -The guide explains how to implement all the functions defined by the [IOptimismMintableERC20](https://github.com/ethereum-optimism/optimism/blob/v1.1.4/packages/contracts-bedrock/src/universal/IOptimismMintableERC20.sol) interface such as the logic for the `mint`, `burn`, `remoteToken`, and `bridge` functions of the `IOptimismMintableERC20` interface. +Lisk uses the [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io/blob/master/optimism.tokenlist.json) as a reference for tokens that have been deployed on Lisk. - +- [Deploying a Standard ERC-20 token](./standard-token.md) +- [Deploying a Custom ERC-20 token](./custom-token.mdx) +### Step 2: Submit details of your token +Follow the instructions in the [GitHub repository](https://github.com/ethereum-optimism/ethereum-optimism.github.io) and submit a PR containing the required details for your token. +**Important:** You must specify in your token's `data.json` file a section for `lisk-sepolia` and/or `lisk`. +[This PR](https://github.com/ethereum-optimism/ethereum-optimism.github.io/pull/899) shows the changes necessary to add the LSK token to the Superchain Token Registry. +The change you need to submit is particularly simple if your token has already been added to the Superchain Token Registry. +For example, [this PR](https://github.com/ethereum-optimism/ethereum-optimism.github.io/commit/27ab9b2d3388f7feba3a152e0a0748c73d732a68) shows the change required for cbETH, which was already on Superchain Token Registry and relies on the Base standard bridge. + +### Step 3: Await final approval +Reviews are regularly conducted by the Lisk team and you should receive a reply within 24-72 hours (depending on if the PR is opened on a weekday, weekend or holiday). diff --git a/docs/building-on-lisk/interacting-with-the-blockchain/viem.mdx b/docs/building-on-lisk/interacting-with-the-blockchain/viem.mdx index 2d4415dc7..145b7ce6c 100644 --- a/docs/building-on-lisk/interacting-with-the-blockchain/viem.mdx +++ b/docs/building-on-lisk/interacting-with-the-blockchain/viem.mdx @@ -1,6 +1,6 @@ --- title: ...with viem -slug: /interacting-with-blockchain/viem +slug: /building-on-lisk/interacting-with-blockchain/viem description: Documentation for using Viem, a TypeScript interface for EVM-compatible blockchains. This page covers installation, setup, and various functionalities such as reading and writing blockchain data and interacting with smart contracts on Lisk. keywords: [ diff --git a/sidebars.js b/sidebars.js index 587408d70..8a8263fd7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -53,19 +53,15 @@ const sidebars = { }, { type: 'category', - label: 'Deploying an ERC-20 token to Lisk', + label: 'Bridging an L1 token to Lisk', collapsible: true, collapsed: true, items: [ + 'building-on-lisk/add-token-to-lisk/index', 'building-on-lisk/add-token-to-lisk/standard-token', 'building-on-lisk/add-token-to-lisk/custom-token', ], - link: { - type: 'doc', - id: 'building-on-lisk/add-token-to-lisk/index', - }, }, - /* 'building-on-lisk/bridge-tokens-to-lisk', */ { type: 'category', label: 'Interacting with the blockchain',