Release 08.08.2024 (#189)

Includes:

- #180

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.
+<!-- TODO: Add reference to Bridges tokens addresses page, once created for Lisk: https://docs.optimism.io/builders/app-developers/bridging/standard-bridge#searching-the-token-list -->
 
-<!-- Lisk uses [Optimism's 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. -->
+:::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.
+:::
 
-<!-- :::warning
+Developers who are creating their own bridged tokens should consider [adding their token to the list](#adding-your-token-to-the-superchain-token-list).
 
-Tokens approved in the GitHub repository are not necessarily listed on the [Lisk Bridge](https://sepolia-bridge.lisk.com).
+Tokens on the Superchain Token List will automatically appear on certain tools like the [Superchain Bridges UI](https://app.optimism.io/bridge).
+However, tokens are not necessarily listed on the [Lisk Bridge UI](https://bridge.lisk.com/bridge/lisk); their listing is neither guaranteed nor automatic.
+Lisk Bridge reviews are conducted manually by the Lisk team.
 
-**Disclaimer:** 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 rely on the preliminary checks put in place, which include the [**automated checks**](https://github.com/ethereum-optimism/ethereum-optimism.github.io?tab=readme-ov-file#automated-checks) 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.
 
-<!-- ## Adding your token to the list
+:::tip
+This bridging mechanism functions identically in both directions — tokens native to Lisk can be bridged to Ethereum, just like tokens native to Ethereum can be bridged to Lisk.
+:::
 
-To add your token to the Lisk Token list, perform the following steps. -->
+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.
 
-<!-- ### Step 2: Submit details of your token
+To add your token to the list, perform the following steps.
 
-Follow the instructions in the [ethereum-optimism.github.io repository's README](https://github.com/ethereum-optimism/ethereum-optimism.github.io?tab=readme-ov-file#superchain-token-list) and submit a pull request containing the required details for your token.
-You must specify a section for `lisk-sepolia` and/or `lisk` in your token's `data.json` file.
-For more information, check out the currently active [pull requests](https://github.com/ethereum-optimism/ethereum-optimism.github.io/pulls) for adding an ERC-20 token to the Lisk network.
+### Step 1: Deploy your token on Lisk
+Select your preferred bridging framework and use it to deploy an ERC-20 for your token on Lisk.
+We recommend you use the framework provided by Lisk's [standard bridge](#the-standard-bridge) contracts and, furthermore, deploy your token using the [OptimismMintableERC20Factory](https://docs.lisk.com/contracts#lisk-network-l2). 
+Deploying your token on Lisk in this manner provides us with guarantees that will smooth the approval process.
+If you choose a different bridging framework, its interface must be compatible with that of the standard bridge.
+Otherwise, it may be difficult for us to support them.
 
-### Step 3: Await final approval
+For step-by-step instructions on how to deploy ERC-20 tokens on Lisk, check the following guides:
 
-Tokens approved in the GitHub repository are not necessarily listed on the Lisk Bridge; their listing is neither guaranteed nor automatic.
-Lisk Bridge reviews are conducted manually by the Lisk team.
-For more information, please visit our [Discord](https://lisk.chat/). -->
+- [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).

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:
   [

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',