How to configure your Orbit chain using the Orbit SDK
In this how-to, you'll learn how to configure your Orbit chain using the Orbit SDK.
This document is under construction and may change significantly as we incorporate style guidance and feedback from readers. Feel free to request specific clarifications by clicking the Request an update button at the top of this document.
Orbit chains have three areas of configuration:
- Parent chain configuration
- Node configuration
- Child chain configuration
1. Parent chain configuration
Configuring the parent chain is the initial step to setting up your Orbit chain. Most of the parent chain configurations are specified during the setup phase. Detailed instructions can be found in the Rollup Deployment Parameters section of the Rollup deployment guide.
After the initial setup, the chain owner can modify configurations as needed. For instance, the validator set can be updated by invoking the setValidKeyset function with a new set of validators. This adaptability facilitates your chain's optimization and management.
2. Node configuration
As a chain deployer, you can configure a node during the node config generation process with the nodeConfig.json file. nodeConfig.json allows you to set up a node as a validator or a sequencer and specify requirements or performance criteria. For more information, refer to the Node Configuration Preparation documentation.
3. Child chain parameter configuration
The child chain configuration can be performed after the chain has been initialized and the token bridge has been deployed. Child chains' parameters are configurable via setter functions in the ArbOwner precompile. Additionally, there are various getter functions in the ArbOwner precompile that you can use to read the current configuration.
Below, we explain several methods in the ArbOwner precompile that you can use to configure the parameters or read their current state.
Setter functions
You can use these setter functions to configure the child chain parameters:
| Parameter | Description |
|---|---|
addChainOwner | Adds a new chain owner to your Orbit chain. |
removeChainOwner | Removes an existing owner from the list of chain owners. |
setMinimumL2BaseFee | Sets the minimum base fee on the child chain. The minimum base fee is the lowest amount that the base fee on the child chain can ever be. For example, the current minimum base fee on Arbitrum One and Arbitrum Nova is 0.01 gwei. |
setSpeedLimit | The fee mechanism on the Arbitrum Nitro stack differs from the Ethereum blockchain. The Nitro stack has a parameter called the speed limit, which targets the number of gas consumed on the child chain per second. If the amount of gas per second exceeds this pre-specified amount, the base fee on the child chain will increase, and vice versa. The current speed limit on Arbitrum One is 7 million gas per second, meaning if the Arbitrum One chain consumes more than 7 million gas per second, its base fee will increase. For more information on the speed limit, please refer to this document explaining the concept of speed limit in the Nitro stack. |
setInfraFeeAccount | Sets the infrastructure fee account address, which receives all fees collected on the child chain. It is meant to receive the minimum base fee, with any amount above that going to the network fee account. |
setNetworkFeeAccount | Sets the network fee account address. As mentioned, this address collects all fees above the base fee. Note that if you set this amount to the 0 address on your chain, all fees will be deposited into the infrastructure fee account. |
scheduleArbOSUpgrade | If you plan to upgrade the ArbOS version of your chain, this method can help you schedule the upgrade. For a complete guide, please refer to the explanation for the arbos upgrade. |
setChainConfig | We discussed the chainConfig in the Rollup deployment guide in detail. If you wish to change any field of the chainConfig, you need to use this method on the child chain. |
Getter functions
| Parameter | Description |
|---|---|
getAllChainOwners | Provides the list of all current chain owners. |
isChainOwner | Allows you to check whether an address is on the list of chain owners. |
getInfraFeeAccount | Returns the infrastructure fee account address. |
getNetworkFeeAccount | Returns the network fee account address. |
Configuring the child chain using the Orbit SDK
In the Orbit SDK, we use the Client Extension feature of Viem to extend the public client. In the Orbit SDK, we defined arbOwnerPublicActions to use it and extend the client on Viem. An example of creating a public client extended with arbOwner public actions is:
import { createPublicClient, http } from 'viem';
import { arbOwnerPublicActions } from '@arbitrum/orbit-sdk';
const client = createPublicClient({
chain: arbitrumLocal,
transport: http(),
}).extend(arbOwnerPublicActions);
With arbOwnerPublicActions and the public client in the Orbit SDK, we've added two new methods to the public clients:
1. arbOwnerReadContract
This method can be used to read the parameters of the child chain discussed in the previous section. An example of using this method with the client defined in the previous section is:
const result = await client.arbOwnerReadContract({
functionName: 'getAllChainOwners',
});
The other parameters can be obtained by changing the function names in the the Getter functions section list.
2. arbOwnerPrepareTransactionRequest
This method can be used to configure the parameters on the ArbOwner precompile, which are listed in the Setter functions section. An example of utilizing this method to configure parameters using the client defined in the previous section is:
// Adding a random address as chain owner using the upgrade executor
const transactionRequest = await client.arbOwnerPrepareTransactionRequest({
functionName: 'addChainOwner',
args: [randomAccountAddress],
upgradeExecutor: false,
account: owner.address,
});
// Submitting the transaction to add a chain owner
await client.sendRawTransaction({
serializedTransaction: await owner.signTransaction(transactionRequest),
});
To use this method, as shown in the example above, some inputs need to be defined:
| Parameter | Description |
|---|---|
functionName | The name of the method you want to use to set the parameter, which can be found in the Setter functions section. |
args | The arguments for the defined function. |
upgradeExecutor | Specifies whether a upgradeExecutor contract governs your chain. If it is not using a upgradeExecutor, you can set it to false, similar to the example above. |
account | Defines the chain owner if an upgradeExecutor does not govern the chain. |
If a upgradeExecutor contract governs your chain, then you need to use the arbOwnerPrepareTransactionRequest method, similar to the example below:
// Adding a random address as chain owner using the upgrade executor
const transactionRequest = await client.arbOwnerPrepareTransactionRequest({
functionName: 'addChainOwner',
args: [randomAccountAddress],
upgradeExecutor: upgradeExecutorAddress,
account: owner.address,
});
// Submitting the transaction to add a chain owner
await client.sendRawTransaction({
serializedTransaction: await owner.signTransaction(transactionRequest),
});
In this example, all the fields are the same as in the first example, except the upgradeExecutor field, which you need to set to the upgradeExecutor address, and the account parameter, which needs to be set to the owner of the upgradeExecutor contract.