docs: token-bridging

docs/build-decentralized-apps/custom-gas-token-sdk.mdx

@@ -41,7 +41,7 @@ You should use `EthBridger` when bridging the native token between the parent ch
 
 ## Registering a custom token in the Token Bridge
 
-When [registering a custom token in the Token Bridge](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#setting-up-your-token-with-the-generic-custom-gateway) of a custom-gas-token Arbitrum chain, there's an additional step to perform before calling `registerTokenToL2`.
+When [registering a custom token in the Token Bridge](/how-arbitrum-works/deep-dives/token-bridging.mdx#setting-up-your-token-with-the-generic-custom-gateway) of a custom-gas-token Arbitrum chain, there's an additional step to perform before calling `registerTokenToL2`.
 
 Since the Token Bridge [router](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/ethereum/gateway/L1OrbitGatewayRouter.sol#L142-L144) and the [generic-custom gateway](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/ethereum/gateway/L1OrbitCustomGateway.sol#L203-L210) expect to have allowance to transfer the native token from the `msg.sender()` to the inbox contract, it's usually the token in the parent chain who handles those approvals. In the [TestCustomTokenL1](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/test/TestCustomTokenL1.sol#L158-L168), we offer as an example of implementation. We see that the contract transfers the native tokens to itself and then approves the router and gateway contracts. If we follow that implementation, we only need to send an approval transaction to the native token to allow the `TestCustomTokenL1` to transfer the native token from the caller of the `registerTokenToL2` function to itself.
 

docs/build-decentralized-apps/token-bridging/01-overview.mdx

@@ -15,5 +15,5 @@ The following sections provide a series of conceptual documents that explain how
 This section has three parts:
 
 - [`ETH` bridging](/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx): explains how Arbitrum handles bridging `ETH`, the native token of Ethereum and the Arbitrum chains, between the parent and child chain.
-- [`ERC-20` token bridging](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx): explains the architecture of the token bridge for this type of asset, describing the different options available to make a token bridgeable.
+- [`ERC-20` token bridging](/how-arbitrum-works/deep-dives/token-bridging.mdx): explains the architecture of the token bridge for this type of asset, describing the different options available to make a token bridgeable.
 - [Bridge tokens programmatically](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx): goes over the process of making an `ERC-20` token bridgeable using the different types of gateways available in the token bridge.

docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx

@@ -12,9 +12,9 @@ This section offers a series of how-tos showcasing the different methods availab
 
 You have three options to consider when deciding on how to bridge your token:
 
-1. [Standard gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx): opt for this method if you want to have a standard `ERC-20` token automatically deployed on Arbitrum, which will act as the child chain counterpart to your parent chain token. For additional information, please refer to the [standard `ERC-20` gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging) in the conceptual page.
-2. [Generic-custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx): choose this method if you require custom functionality for your `ERC-20` token on Arbitrum. You will deploy your counterpart token on Arbitrum equipped with the unique features you wish to implement. For additional information, please refer to the [Arbitrum generic custom gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#the-arbitrum-generic-custom-gateway) in the conceptual page.
-3. [Custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx): This method is intended for edge cases where a custom `ERC-20` token is insufficient. You will need an additional layer of flexibility with the gateway (for example, your token has the capacity to increase its supply on the child chain, and you want those child chain-minted tokens to be withdrawable back to the parent chain and recognized by the parent chain contract). For additional information, please refer to the [other types of gateways](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#other-flavors-of-gateways) in the conceptual page.
+1. [Standard gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx): opt for this method if you want to have a standard `ERC-20` token automatically deployed on Arbitrum, which will act as the child chain counterpart to your parent chain token. For additional information, please refer to the [standard `ERC-20` gateway](/how-arbitrum-works/deep-dives/token-bridging.mdx#default-standard-bridging) in the conceptual page.
+2. [Generic-custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx): choose this method if you require custom functionality for your `ERC-20` token on Arbitrum. You will deploy your counterpart token on Arbitrum equipped with the unique features you wish to implement. For additional information, please refer to the [Arbitrum generic custom gateway](/how-arbitrum-works/deep-dives/token-bridging.mdx#the-arbitrum-generic-custom-gateway) in the conceptual page.
+3. [Custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx): This method is intended for edge cases where a custom `ERC-20` token is insufficient. You will need an additional layer of flexibility with the gateway (for example, your token has the capacity to increase its supply on the child chain, and you want those child chain-minted tokens to be withdrawable back to the parent chain and recognized by the parent chain contract). For additional information, please refer to the [other types of gateways](/how-arbitrum-works/deep-dives/token-bridging.mdx#other-flavors-of-gateways) in the conceptual page.
 
 ## What if I want to bridge a token programmatically?
 

docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx

@@ -6,7 +6,7 @@ content_type: how-to
 displayed_sidebar: buildAppsSidebar
 ---
 
-In this how-to, you’ll learn how to bridge your own token between Ethereum (parent chain) and Arbitrum (child chain), using [Arbitrum’s standard `ERC20` gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx).
+In this how-to, you’ll learn how to bridge your own token between Ethereum (parent chain) and Arbitrum (child chain), using [Arbitrum’s standard `ERC20` gateway](/how-arbitrum-works/deep-dives/token-bridging.mdx#default-standard-bridging). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx).
 
 Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.mdx), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Remix)](/build-decentralized-apps/01-quickstart-solidity-remix.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required.
 
@@ -75,7 +75,7 @@ main()
 
 ## Step 2: Identify the bridge contracts to call (concepts summary)
 
-As stated in the [token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging), when using Arbitrum’s standard `ERC-20` gateway, you don’t need to do any pre-configuration process. Your token will be “bridgeable” out of the box.
+As stated in the [token bridge conceptual page](/how-arbitrum-works/deep-dives/token-bridging.mdx#default-standard-bridging), when using Arbitrum’s standard `ERC-20` gateway, you don’t need to do any pre-configuration process. Your token will be “bridgeable” out of the box.
 
 As explained in the conceptual page, there are two contracts that we need to be aware of when bridging tokens:
 
@@ -211,7 +211,7 @@ const l2Token = erc20Bridger.getChildTokenContract(l2Provider, l2TokenAddress);
 
 To do this operation manually, you can call the method `calculateL2TokenAddress` of the router contract.
 
-If you visit that address on [Arbiscan](https://arbiscan.io/), you’ll notice that it is a copy of the contract [`StandardArbERC20`](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/StandardArbERC20.sol). This is the standard contract that is automatically created the first time a token that doesn’t exist in Arbitrum is bridged. [The token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging) has more information about this contract.
+If you visit that address on [Arbiscan](https://arbiscan.io/), you’ll notice that it is a copy of the contract [`StandardArbERC20`](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/StandardArbERC20.sol). This is the standard contract that is automatically created the first time a token that doesn’t exist in Arbitrum is bridged. [The token bridge conceptual page](/how-arbitrum-works/deep-dives/token-bridging.mdx#default-standard-bridging) has more information about this contract.
 
 ## Conclusion
 

docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx

@@ -6,15 +6,15 @@ content_type: how-to
 displayed_sidebar: buildAppsSidebar
 ---
 
-In this how-to, you’ll learn how to bridge your own token between Ethereum (parent chain) and Arbitrum (child chain), using [Arbitrum’s generic-custom gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#the-arbitrum-generic-custom-gateway). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx).
+In this how-to, you’ll learn how to bridge your own token between Ethereum (parent chain) and Arbitrum (child chain), using [Arbitrum’s generic-custom gateway](/how-arbitrum-works/deep-dives/token-bridging.mdx#the-arbitrum-generic-custom-gateway). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx).
 
 Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.mdx), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Hardhat)](/build-decentralized-apps/01-quickstart-solidity-remix.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required.
 
 We will go through all the steps involved in the process. However, if you want to jump straight to the code, we have created [this script in our tutorials repository](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/custom-token-bridging) that encapsulates the entire process.
 
 ## Step 1: Review the prerequisites
 
-As stated in the [token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#the-arbitrum-generic-custom-gateway), there are a few prerequisites to keep in mind while using this method to make a token bridgeable.
+As stated in the [token bridge conceptual page](/how-arbitrum-works/deep-dives/token-bridging.mdx#the-arbitrum-generic-custom-gateway), there are a few prerequisites to keep in mind while using this method to make a token bridgeable.
 
 First of all, the **parent chain counterpart of the token**, must conform to the [`ICustomToken`](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/ethereum/ICustomToken.sol) interface, meaning that:
 

docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx → docs/how-arbitrum-works/deep-dives/token-bridging.mdx

@@ -1,11 +1,10 @@
 ---
-title: 'ERC-20 token bridging'
-description: Describes how bridging ERC-20 tokens works on Arbitrum and the architecture of the token bridge
+title: 'Token bridging'
+description: Describes how token bridging works on Arbitrum and the architecture of the token bridge
 author: dzgoldman
-user_story: As a developer, I want to understand how ERC-20 token bridging works on Arbitrum, and the architecture of the token bridge.
+user_story: As a developer, I want to understand how token bridging works on Arbitrum, and the architecture of the token bridge.
 content_type: concept
-sidebar_position: 3
-displayed_sidebar: buildAppsSidebar
+displayed_sidebar: howItWorksSidebar
 ---
 
 import ImageZoom from '@site/src/components/ImageZoom';
@@ -113,7 +112,7 @@ Your token on the parent chain should conform to the [ICustomToken](https://gith
 
 Your token should conform to the minimum [`IArbToken`](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/IArbToken.sol) interface; i.e., it should have `bridgeMint` and `bridgeBurn` methods only callable by the `L2CustomGateway` contract, and the address of its corresponding Ethereum token accessible via `l1Address`. For an example implementation, see [`L2GatewayToken`](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/libraries/L2GatewayToken.sol).
 
-import TokenCompatibilityPartial from './partials/_token-compatibility.mdx';
+import TokenCompatibilityPartial from '../../build-decentralized-apps/token-bridging/partials/_token-compatibility.mdx';
 
 <TokenCompatibilityPartial />
 

docs/launch-arbitrum-chain/03-deploy-an-arbitrum-chain/05-deploying-token-bridge.mdx

@@ -219,7 +219,7 @@ const tokenBridgeContracts = await txReceipt.getTokenBridgeContracts({
 
 That step only applies to ETH-based Arbitrum chains (i.e., not custom gas token chains). The canonical bridge design has a separate custom gateway for `WETH` to bridge it in and out of the Arbitrum chain.
 
-You can find more info about `WETH` gateways in our ["other gateways flavors" documentation](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#other-flavors-of-gateways).
+You can find more info about `WETH` gateways in our ["other gateways flavors" documentation](/how-arbitrum-works/deep-dives/token-bridging.mdx#other-flavors-of-gateways).
 
 :::
 

docs/launch-arbitrum-chain/06-third-party-integrations/01-bridged-usdc-standard.md

@@ -11,7 +11,7 @@ Circle’s [Bridged `USDC` Standard](https://www.circle.com/blog/bridged-usdc-st
 
 ## Why adopt the bridged `USDC` standard?
 
-When `USDC` is bridged into an Arbitrum chain, the default path is to use the chain’s [canonical gateway contracts for `ERC-20`'s](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx). By way of example, when a user bridges `USDC` from Arbitrum One to an Arbitrum chain, their Arbitrum One `USDC` tokens are locked into the Arbitrum chain’s parent side bridge, and a representative `USDC` token is minted to the user’s address on the Arbitrum chain, via the child side bridge.
+When `USDC` is bridged into an Arbitrum chain, the default path is to use the chain’s [canonical gateway contracts for `ERC-20`'s](/how-arbitrum-works/deep-dives/token-bridging.mdx). By way of example, when a user bridges `USDC` from Arbitrum One to an Arbitrum chain, their Arbitrum One `USDC` tokens are locked into the Arbitrum chain’s parent side bridge, and a representative `USDC` token is minted to the user’s address on the Arbitrum chain, via the child side bridge.
 
 The challenge with this user flow is two-fold:
 
@@ -41,7 +41,7 @@ Other requirements:
 
 - It is assumed there is already a `USDC` token deployed and used on the parent chain.
 - Also, it is assumed that the standard Arbitrum chain ownership system is used, i.e., `UpgradeExecutor` is the owner of the `ownable` contracts, and there is an EOA or multi-sig that has the executor role on the `UpgradeExecutor`.
-- Refer to the [token bridge overview page](/launch-arbitrum-chain/03-deploy-an-arbitrum-chain/05-deploying-token-bridge.mdx) for more information about the token bridge design and operational dynamics. You can learn more in our [overview of gateways operating models](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#other-flavors-of-gateways).
+- Refer to the [token bridge overview page](/launch-arbitrum-chain/03-deploy-an-arbitrum-chain/05-deploying-token-bridge.mdx) for more information about the token bridge design and operational dynamics. You can learn more in our [overview of gateways operating models](/how-arbitrum-works/deep-dives/token-bridging.mdx#other-flavors-of-gateways).
 
 ## Deployment steps
 

sidebars.js

@@ -1101,6 +1101,11 @@ const sidebars = {
               label: 'Gas and fees',
               id: 'how-arbitrum-works/deep-dives/gas-and-fees',
             },
+            {
+              type: 'doc',
+              label: 'Token bridging',
+              id: 'how-arbitrum-works/deep-dives/token-bridging',
+            },
           ],
         },
         {
@@ -1321,11 +1326,6 @@ const sidebars = {
               label: 'ETH bridging',
               id: 'build-decentralized-apps/token-bridging/token-bridge-ether',
             },
-            {
-              type: 'doc',
-              label: 'ERC-20 token bridging',
-              id: 'build-decentralized-apps/token-bridging/token-bridge-erc20',
-            },
             {
               type: 'category',
               label: 'Bridge tokens programmatically',

vercel.json

@@ -2295,6 +2295,11 @@
       "destination": "/launch-arbitrum-chain/deploy-an-arbitrum-chain/deploying-an-arbitrum-chain",
       "permanent": false
     },
+    {
+      "source": "/(build-decentralized-apps/token-bridging/token-bridge-erc20/?)",
+      "destination": "/how-arbitrum-works/deep-dives/token-bridging",
+      "permanent": false
+    },
     {
       "source": "/(withdrawals/?)",
       "destination": "/how-arbitrum-works/deep-dives/transaction-lifecycle",