SDK support for custom gas token Orbit chains
Arbitrum SDK is a TypeScript library for client-side interactions with Arbitrum. It provides common helper functionality as well as access to the underlying smart contract interfaces.
Custom gas token APIs
Custom gas token support in the Arbitrum SDK introduces a suite of APIs designed for the specific purpose of facilitating bridging operations. These APIs are tailored for use cases where there is a need to transfer a native token or an ERC-20
token from the parent chain to an orbit chain utilizing a custom gas token
. The process involves an initial step of authorizing the native token on the parent chain. To streamline this, our APIs provide functionalities for token approval and offer a mechanism to verify the current status of this approval. Detailed below is a guide to how each of these APIs can be effectively utilized for distinct purposes:
-
EthBridger
Context:- APIs:
getApproveGasTokenRequest
andapproveGasToken
. - Purpose: These APIs are essential for the bridging of native tokens to the Orbit chain. They facilitate the necessary approval for native tokens, allowing contracts to manage fund movements. This process includes escrowing a specified amount of the native token on the parent chain and subsequently bridging it to the Orbit chain.
- APIs:
You should use EthBridger
when bridging the native token between the parent chain and the Orbit chain.
Erc20Bridger
Context:- APIs:
getApproveGasTokenRequest
andapproveGasToken
. - Purpose: In the scenario of bridging
ERC-20
assets to an Orbit chain, these APIs play a crucial role. Token Bridging on Arbitrum Nitro stack uses retryable tickets and needs a specific fee to be paid for the creation and redemption of the ticket. For more information about retryable tickets, please take a look at our chapter about retryable tickets part of our docs. The Orbit chain operates as a custom gas token network, necessitating the payment of fees in native tokens for the creation of retryable tickets and their redemption on the Orbit chain. To cover the submission and execution fees associated with retryable tickets on the Orbit chain, an adequate number of native tokens must be approved and allocated to the parent chain to cover the fees.
- APIs:
- You should use
Erc20Bridger
when bridging anERC-20
token between the parent chain and the orbit chain. - These APIs are just needed for
custom gas token
Orbit chains and forETH
-powered rollup and Anytrust Orbit chains, you don't need to use them. - When native tokens are transferred to the custom gas token Orbit chain, they function equivalently to
ETH
on EVM chains. This means these tokens will exhibit behavior identical to that ofETH
, the native currency on EVM chains. This similarity in functionality is a key feature to consider in transactions and operations within the Orbit chain. - everything else is under the hood, and the custom gas token code paths will be executed just if the
L2Network
object config has anativeToken
field.
Registering a custom token in the Token Bridge
When registering a custom token in the Token Bridge of a custom-gas-token Orbit chain, there's an additional step to perform before calling registerTokenToL2
.
Since the Token Bridge router and the generic-custom gateway 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, 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.
You can find a tutorial that deploys two tokens and registers them in the Token Bridge of a custom-gas-token-based chain.