From 653bca0ef9924cdf509fa1635156fdda55b7e629 Mon Sep 17 00:00:00 2001 From: gmehta2 <39961155+gmehta2@users.noreply.github.com> Date: Tue, 20 Jan 2026 10:05:08 -0500 Subject: [PATCH 1/9] Create Predeploy contracts --- .../common/Predeploy contracts | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts b/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts new file mode 100644 index 0000000000..6a83cb623b --- /dev/null +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts @@ -0,0 +1,68 @@ +--- +title: 'Predeploy Contracts' +sidebar_label: 'Predeploy Contracts' +description: 'Start your chain with predeployed contracts' +author: Mehta +sme: Mehta +user_story: As a current Arbitrum chain owner, I need to start my chain with a set of predeployed contracts. +content_type: get-started +--- + +## What is this feature? +Orbit chain operators are increasingly looking to deploy chains with pre-existing state, by loading an initial state in a file such as `genesis.json`. +Specifically, Raases want to predeploy smart contracts (like Gnosis Safe) to an Orbit chain so they exist at genesis, before any user interaction or post-launch governance. + +Initializing from a genesis state would be helpful in the following scenarios: + +1. Redeploying a new testnet with pre-existing state if current testnet is broken +2. Deploying additional sibling chains with pre-existing contracts +3. Simplifies RaaSes backend for self-serve, where there can be 100s of testnets being deployed with similar contracts +4. Reduce lift on 3rd-party infrastructure teams to redeploy contracts for new chains + + +### **What Does This Feature Do?** + +1. The Ethereum ecosystem uses `genesis.json` to define the initial state of chains +2. A key use case of `genesis.json` is preloading smart contracts in the very first block + - Predeploy contract with state set up + - Bake in a sample set of contracts (compile genesis.json into nitro itself) + +## Default Contracts for Predeploys +Safe 0x69f4D1788e39c87893C980c06EdF4b7f686e2938 +SafeL2 0xfb1bffC9d739B8D520DaF37dF666da4C687191EA +GnosisSafeProxyFactory v1.3.0 +Safe (add versions) - create scw +Safe Singleton Factory 0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7 +MultiSend 0x998739BFdAAdde7C933B942a68053933098f9EDa +MultiSendCallOnly 0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B +Multicall3 0xcA11bde05977b3631167028862bE2a173976CA11 +create2Deployer 0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2 +CreateX 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed +Arachnid's Deterministic Deployment Proxy 0x4e59b44847b379578588920cA78FbF26c0B4956C +Permit2 0x000000000022D473030F116dDEE9F6B43aC78BA3 +ERC-4337 v0.6.0 EntryPoint 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 +SenderCreator dependency @ 0x7fc98430eAEdbb6070B35B39D798725049088348 on ETH mainnet +ERC-4337 v0.6.0 SenderCreator 0x7fc98430eAEdbb6070B35B39D798725049088348 +ERC-4337 v0.7.0 EntryPoint 0x0000000071727De22E5E9d8BAf0edAc6f37da032 +SenderCreator dependency @ 0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C on ETH mainnet +ERC-4337 v0.8.0 EntryPoint 0x4337084d9e255ff0702461cf8895ce9e3b5ff108 +ERC-4337 v0.7.0 SenderCreator +ERC-4337 Safe Module Setup 0x2dd68b007B46fBe91B9A7c3EDa5A7a1063cB5b47 +ERC-4337 Safe Module 0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226 +EAS 0x4200000000000000000000000000000000000021 + + +### **How to use this feature?** +1. Specify Nitro contract version: v3.2, which is ready for genesis.json support +2. Generate the genesis.json file and obtain the genesis blockhash and sendRoot hash + 1. Use the genesis-file-generator tool available at https://github.com/OffchainLabs/genesis-file-generator, to generate a standard genesis.json file with a set of pre-deploy contracts. + 2. You can also generate your own genesis.json file, but carefully read [this notice](https://github.com/OffchainLabs/genesis-file-generator#exclamation-important-note-about-the-chain-config-property) before proceeding with the next steps. + 3. After the genesis.json file is created, use [nitro’s genesis-generator tool](https://github.com/OffchainLabs/nitro/blob/v3.9.2/cmd/genesis-generator/genesis-generator.go) to obtain the genesis blockhash and sendRoot hash. +3. If you want to edit or customize the predeploys, visit the `genesis.json` file and make updates +4. Use the SDK to deploy your chain with the new parameter you get from step 2 `(assertion_hash)`. SDK will generate this — you will need to input blockhash and sendRoot. +5. Create the node configuration for your node + 1. Craft the node configuration of your node as you normally do, and additionally, set the following properties: + 1. --init.genesis-json-file=/path/to/genesis.json + 2. If nitro already support another way to start the chain - `--chain.initial-l1base-fee` (potential flag) + +**Start your chain** with the correct preloaded state. From 3c07dedceac76111d9300d65d782fa86cbfe330e Mon Sep 17 00:00:00 2001 From: Allan Date: Tue, 20 Jan 2026 11:36:45 -0600 Subject: [PATCH 2/9] minor wording / grammatical nits --- .../02-configure-your-chain/common/Predeploy contracts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts b/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts index 6a83cb623b..ff1c229aae 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts @@ -9,15 +9,15 @@ content_type: get-started --- ## What is this feature? -Orbit chain operators are increasingly looking to deploy chains with pre-existing state, by loading an initial state in a file such as `genesis.json`. -Specifically, Raases want to predeploy smart contracts (like Gnosis Safe) to an Orbit chain so they exist at genesis, before any user interaction or post-launch governance. +Arbitrum chain operators are increasingly looking to deploy chains with pre-existing state, by loading an initial state in a file such as `genesis.json`. +Specifically, Raases want to predeploy smart contracts (like Gnosis Safe) to an Arbitrum chain so they exist at genesis, before any user interaction or post-launch governance. Initializing from a genesis state would be helpful in the following scenarios: 1. Redeploying a new testnet with pre-existing state if current testnet is broken 2. Deploying additional sibling chains with pre-existing contracts -3. Simplifies RaaSes backend for self-serve, where there can be 100s of testnets being deployed with similar contracts -4. Reduce lift on 3rd-party infrastructure teams to redeploy contracts for new chains +3. Simplifying self-serve backends for RaaSes, such that 100s of testnets can be deployed with similar contracts +4. Reducing lift on 3rd-party infrastructure teams to redeploy contracts for new chains ### **What Does This Feature Do?** From af52682008c8df56d8de12305093c18e5a11fbc9 Mon Sep 17 00:00:00 2001 From: asomani-ocl Date: Thu, 29 Jan 2026 16:03:09 +0530 Subject: [PATCH 3/9] initial changes to custom genesis --- .../common/Predeploy contracts | 68 ----------- .../common/use-a-custom-genesis.mdx | 108 ++++++++++++++++++ 2 files changed, 108 insertions(+), 68 deletions(-) delete mode 100644 docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts create mode 100644 docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts b/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts deleted file mode 100644 index ff1c229aae..0000000000 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/Predeploy contracts +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: 'Predeploy Contracts' -sidebar_label: 'Predeploy Contracts' -description: 'Start your chain with predeployed contracts' -author: Mehta -sme: Mehta -user_story: As a current Arbitrum chain owner, I need to start my chain with a set of predeployed contracts. -content_type: get-started ---- - -## What is this feature? -Arbitrum chain operators are increasingly looking to deploy chains with pre-existing state, by loading an initial state in a file such as `genesis.json`. -Specifically, Raases want to predeploy smart contracts (like Gnosis Safe) to an Arbitrum chain so they exist at genesis, before any user interaction or post-launch governance. - -Initializing from a genesis state would be helpful in the following scenarios: - -1. Redeploying a new testnet with pre-existing state if current testnet is broken -2. Deploying additional sibling chains with pre-existing contracts -3. Simplifying self-serve backends for RaaSes, such that 100s of testnets can be deployed with similar contracts -4. Reducing lift on 3rd-party infrastructure teams to redeploy contracts for new chains - - -### **What Does This Feature Do?** - -1. The Ethereum ecosystem uses `genesis.json` to define the initial state of chains -2. A key use case of `genesis.json` is preloading smart contracts in the very first block - - Predeploy contract with state set up - - Bake in a sample set of contracts (compile genesis.json into nitro itself) - -## Default Contracts for Predeploys -Safe 0x69f4D1788e39c87893C980c06EdF4b7f686e2938 -SafeL2 0xfb1bffC9d739B8D520DaF37dF666da4C687191EA -GnosisSafeProxyFactory v1.3.0 -Safe (add versions) - create scw -Safe Singleton Factory 0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7 -MultiSend 0x998739BFdAAdde7C933B942a68053933098f9EDa -MultiSendCallOnly 0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B -Multicall3 0xcA11bde05977b3631167028862bE2a173976CA11 -create2Deployer 0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2 -CreateX 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed -Arachnid's Deterministic Deployment Proxy 0x4e59b44847b379578588920cA78FbF26c0B4956C -Permit2 0x000000000022D473030F116dDEE9F6B43aC78BA3 -ERC-4337 v0.6.0 EntryPoint 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789 -SenderCreator dependency @ 0x7fc98430eAEdbb6070B35B39D798725049088348 on ETH mainnet -ERC-4337 v0.6.0 SenderCreator 0x7fc98430eAEdbb6070B35B39D798725049088348 -ERC-4337 v0.7.0 EntryPoint 0x0000000071727De22E5E9d8BAf0edAc6f37da032 -SenderCreator dependency @ 0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C on ETH mainnet -ERC-4337 v0.8.0 EntryPoint 0x4337084d9e255ff0702461cf8895ce9e3b5ff108 -ERC-4337 v0.7.0 SenderCreator -ERC-4337 Safe Module Setup 0x2dd68b007B46fBe91B9A7c3EDa5A7a1063cB5b47 -ERC-4337 Safe Module 0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226 -EAS 0x4200000000000000000000000000000000000021 - - -### **How to use this feature?** -1. Specify Nitro contract version: v3.2, which is ready for genesis.json support -2. Generate the genesis.json file and obtain the genesis blockhash and sendRoot hash - 1. Use the genesis-file-generator tool available at https://github.com/OffchainLabs/genesis-file-generator, to generate a standard genesis.json file with a set of pre-deploy contracts. - 2. You can also generate your own genesis.json file, but carefully read [this notice](https://github.com/OffchainLabs/genesis-file-generator#exclamation-important-note-about-the-chain-config-property) before proceeding with the next steps. - 3. After the genesis.json file is created, use [nitro’s genesis-generator tool](https://github.com/OffchainLabs/nitro/blob/v3.9.2/cmd/genesis-generator/genesis-generator.go) to obtain the genesis blockhash and sendRoot hash. -3. If you want to edit or customize the predeploys, visit the `genesis.json` file and make updates -4. Use the SDK to deploy your chain with the new parameter you get from step 2 `(assertion_hash)`. SDK will generate this — you will need to input blockhash and sendRoot. -5. Create the node configuration for your node - 1. Craft the node configuration of your node as you normally do, and additionally, set the following properties: - 1. --init.genesis-json-file=/path/to/genesis.json - 2. If nitro already support another way to start the chain - `--chain.initial-l1base-fee` (potential flag) - -**Start your chain** with the correct preloaded state. diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx new file mode 100644 index 0000000000..58a6dc065e --- /dev/null +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx @@ -0,0 +1,108 @@ +--- +title: 'Use a custom genesis to deploy your Arbitrum chain' +sidebar_label: 'Use custom genesis' +description: 'Start your chain with a custom genesis file' +author: Mehta +sme: Mehta +user_story: As a current Arbitrum chain owner, I need to start my chain with a set of predeployed contracts and account balances using genesis.json file. +content_type: get-started +--- + +:::caution Minimum Requirement +You must use Nitro contracts v3.2 or higher. This version is the first to include full support for custom `genesis.json` initialization. +::: + +## What is this feature? + +Arbitrum chain operators are increasingly looking to deploy chains with pre-existing state, by loading an initial state in a file such as `genesis.json`. +Specifically, chain operators want to predeploy smart contracts (like Gnosis Safe) to an Arbitrum chain so they exist at genesis, before any user interaction or post-launch governance. + +Initializing from a genesis state would be helpful in the following scenarios: + +1. Redeploying a new testnet with pre-existing state if current testnet is broken +2. Deploying additional sibling chains with pre-existing contracts +3. Simplifying self-serve backends for RaaSes, such that 100s of testnets can be deployed with similar contracts +4. Reducing lift on 3rd-party infrastructure teams to redeploy contracts for new chains + +## **What Does This Feature Do?** + +This feature allows you to initialize a new blockchain with a customized starting state and network configuration through the following options: + +- **Predeployed contracts** - standard chains start without any smart contracts. This feature allows you to preload contract bytecode in the very first block so infrastructure is available at the launch. +- **Initial account state (allocations)** - you can pre-configure the ledger—including account balances and contract storage—before the network opens for transactions. +- **Custom chain configuration** – chain operators can provide a custom chain-config during startup to define unique network parameters like Chain ID, gas pricing behavior etc. + +## **How to use this feature?** + +You can use the feature via the SDK or by using the `genesis-file-generator` tool. + +### Use via chain SDK + +:::caution +The feature is supported in chain SDK versions xx.xx and above. Chain SDK only allows the standard `genesis.json` creation which contains the predeploy contracts. In case you want to customize the `genesis.json` file or pass accounts / custom chain config, you should use the `genesis-generator-tool` for using the feature. +::: +The chain SDK provides an automated script that handles the entire lifecycle: building the genesis state, calculating `blockhash` and `sendRoot` hash, and creating the rollup. + +- **Configure the environment:** the script uses a .env file to manage your chain's identity and gas parameters. +- **Run the custom genesis script:** execute the script to start the automated workflow: + ```bash + npx ts-node scripts/deploy-custom-genesis.ts + ``` +- **SDK workflow:** the script completes the below automated steps: + - Generates a standard `genesis.json` file with the pre-deploys contracts. + - Calculates the `blockhash` and `sendRoot` hash and gives the same as output for you to use. + - An option to deploy the rollup. You can choose to either deploy the chain with the above `genesis.json` or just take the output of the previous step and setup the chain separately. + +### Use via `genesis-file-generator` tool + +- **Prepare the genesis state:** Use the [genesis-file-generator tool](https://github.com/OffchainLabs/genesis-file-generator), to generate a standard `genesis.json` file with a set of pre-deploy contracts. During this process, you can use the following flags to customize your state: + - `--custom-alloc-account-file` – path to a JSON file containing your own account balances, contract bytecodes, and storage slots. + - `--not-load-default-predeploys` – use this flag if you want to skip the standard set of Orbit predeployed contracts and start with a clean slate. + - `--custom-serializedChainConfig` – use this flag to provide your own minified/serialized chain configuration string. + - You can also generate your own genesis.json file, but carefully read [this notice](https://github.com/OffchainLabs/genesis-file-generator#exclamation-important-note-about-the-chain-config-property) before proceeding with the next steps. +- **Generate required hashes:** After the genesis.json file is created, use [nitro’s genesis-generator tool](https://github.com/OffchainLabs/nitro/blob/v3.9.2/cmd/genesis-generator/genesis-generator.go) to obtain the genesis blockhash and sendRoot hash. +- **Deploy the rollup:** use the `blockhash` and `sendRoot` in the chain SDK. The SDK will use these to generate the `assertion_hash` needed to register your rollup's core smart contracts on the parent chain. +- **Configure and launch your node:** set up your node as usual, but include the following properties to point to your custom state: + - `--init.genesis-json-file=/path/to/genesis.json` - path to your custom `genesis.json` file + - `--chain.initial-l1base-fee=[Price]` – input the gas price from the L1 block where your rollup creation transaction was accepted. + +**Start your chain** with the correct preloaded state. + +## Pre-deployed Contracts Registry + +The following contracts are included by default in the standard `genesis.json` file. +| Category | Contract Name | Address | Note | +| :--- | :--- | :--- | :--- | +| **Factories** | Safe Singleton Factory v1.0.43 | `0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7` | Deterministic Proxy (Safe Key) | +| | Create2Deployer | `0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2` | CREATE (Deployer: `0x5542...`, Nonce 0) | +| | CreateX v1.0.0 | `0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed` | Pre-signed Transaction | +| | Arachnid Proxy | `0x4e59b44847b379578588920cA78FbF26c0B4956C` | Deterministic Proxy (Arachnid) | +| **Safe v1.3.0** | GnosisSafe (Canonical) | `0xd9Db270c1B5E3Bd161E8c8503c55cEABeE709552` | Via Arachnid CREATE2 Proxy | +| | GnosisSafe (EIP-155) | `0x69f4D1788e39c87893C980c06EdF4b7f686e2938` | Via Safe Singleton Factory | +| | GnosisSafeL2 (Canonical) | `0x3e5c63644e683549055b9be8653de26e0b4cd36e` | Via Arachnid CREATE2 Proxy | +| | GnosisSafeL2 (EIP-155) | `0xfb1bffC9d739B8D520DaF37dF666da4C687191EA` | Via Safe Singleton Factory | +| | SafeProxyFactory (Canonical) | `0xa6B71E26C5e0845f74c812102Ca7114b6a896AB2` | Via Arachnid CREATE2 Proxy | +| | SafeProxyFactory (EIP-155) | `0xC22834581EbC8527d974F8a1c97E1bEA4EF910BC` | Via Safe Singleton Factory | +| | MultiSend v1.3.0 | `0x998739BFdAAdde7C933B942a68053933098f9EDa` | Via Safe Singleton Factory | +| | MultiSendCallOnly v1.3.0 | `0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B` | Via Safe Singleton Factory | +| **Safe v1.4.1** | Safe | `0x41675C099F32341bf84BFc5382aF534df5C7461a` | Via Safe Singleton Factory | +| | SafeL2 | `0x29fcB43b46531BcA003ddC8FCB67FFE91900C762` | Via Safe Singleton Factory | +| | SafeProxyFactory | `0x4e1DCf7AD4e460CfD30791CCC4F9c8a4f820ec67` | Via Safe Singleton Factory | +| | MultiSend v1.4.1 | `0x38869bf66a61cF6bDB996A6aE40D5853Fd43B526` | Via Safe Singleton Factory | +| | MultiSendCallOnly v1.4.1 | `0x9641d764fc13c8B624c04430C7356C1C7C8102e2` | Via Safe Singleton Factory | +| **ERC-4337 Core** | EntryPoint v0.6.0 | `0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789` | Standard v0.6 | +| | SenderCreator v0.6.0 | `0x7fc98430eAEdbb6070B35B39D798725049088348` | Created during EP v0.6.0 deploy | +| | EntryPoint v0.7.0 | `0x0000000071727De22E5E9d8BAf0edAc6f37da032` | Standard v0.7 | +| | SenderCreator v0.7.0 | `0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C` | Created during EP v0.7.0 deploy | +| | EntryPoint v0.8.0 | `0x4337084d9e255ff0702461cf8895ce9e3b5ff108` | Standard v0.8 | +| | SenderCreator v0.8.0 | `0x449ED7C3e6Fee6a97311d4b55475DF59C44AdD33` | Created during EP v0.8.0 deploy | +| **Account Modules** | Safe Module Setup v0.3.0 | `0x2dd68b007B46fBe91B9A7c3EDa5A7a1063cB5b47` | ERC-4337 Initializer | +| | Safe 4337 Module v0.3.0 | `0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226` | Associated with Entrypoint v0.7.0 | +| | Kernel v3.3 | `0xd6CEDDe84be40893d153Be9d467CD6aD37875b28` | Associated with Entrypoint v0.7.0 | +| | KernelFactory v3.3 | `0x2577507b78c2008Ff367261CB6285d44ba5eF2E9` | Associated with Entrypoint v0.7.0 | +| | MetaFactory v3.0 | `0xd703aaE79538628d27099B8c4f621bE4CCd142d5` | ZeroDev FactoryStaker | +| | ECDSAValidator v3.1 | `0x845ADb2C711129d4f3966735eD98a9F09fC4cE57` | Compiled from commit 8f7fd99 | +| **Infrastructure** | Multicall3 | `0xcA11bde05977b3631167028862bE2a173976CA11` | Pre-signed Transaction | +| | Permit2 | `0x000000000022D473030F116dDEE9F6B43aC78BA3` | Uniswap Permit2 | +| | EAS v1.4.0 | `0xF4C9CCaf46A866e2c12C5Bd95A39694718044444` | Ethereum Attestation Service | +| | EAS SchemaRegistry | `0x822B0B93BE3f3B8Da35a2E90e877C01215be8506` | EAS Registry | From ce06da0cd0d3ad688e87d78c3bed8e0ef05d757e Mon Sep 17 00:00:00 2001 From: asomani-ocl Date: Wed, 11 Mar 2026 16:49:51 +0530 Subject: [PATCH 4/9] update docs for custom genesis based on latest changes --- .../common/use-a-custom-genesis.mdx | 126 +++++++++++++++--- 1 file changed, 109 insertions(+), 17 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx index 58a6dc065e..9eda846af7 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx @@ -9,8 +9,10 @@ content_type: get-started --- :::caution Minimum Requirement -You must use Nitro contracts v3.2 or higher. This version is the first to include full support for custom `genesis.json` initialization. -::: + +- You must use Nitro contracts v3.2 or higher. This version is the first to include full support for custom `genesis.json` initialization. +- Nitro node v3.10.0 or higher is needed for using custom-genesis. + ::: ## What is this feature? @@ -30,7 +32,7 @@ This feature allows you to initialize a new blockchain with a customized startin - **Predeployed contracts** - standard chains start without any smart contracts. This feature allows you to preload contract bytecode in the very first block so infrastructure is available at the launch. - **Initial account state (allocations)** - you can pre-configure the ledger—including account balances and contract storage—before the network opens for transactions. -- **Custom chain configuration** – chain operators can provide a custom chain-config during startup to define unique network parameters like Chain ID, gas pricing behavior etc. +- **Enable advanced features** – chain operators can use this feature to launch a chain with advanced customizations like [mint / burn of gas token via third party bridges](/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-mint-burn) and compliance-focused transaction filtering. ## **How to use this feature?** @@ -43,30 +45,120 @@ The feature is supported in chain SDK versions xx.xx and above. Chain SDK only a ::: The chain SDK provides an automated script that handles the entire lifecycle: building the genesis state, calculating `blockhash` and `sendRoot` hash, and creating the rollup. -- **Configure the environment:** the script uses a .env file to manage your chain's identity and gas parameters. -- **Run the custom genesis script:** execute the script to start the automated workflow: - ```bash - npx ts-node scripts/deploy-custom-genesis.ts - ``` - **SDK workflow:** the script completes the below automated steps: - Generates a standard `genesis.json` file with the pre-deploys contracts. - Calculates the `blockhash` and `sendRoot` hash and gives the same as output for you to use. - An option to deploy the rollup. You can choose to either deploy the chain with the above `genesis.json` or just take the output of the previous step and setup the chain separately. +#### Configuration Reference + +**Core Configuration** \ +Required to generate the `genesis.json` file. +| Variable | Description | +| :--- | :--- | +| `CHAIN_ID` | The unique numeric identifier for your new chain. | +| `IS_ANYTRUST` | Whether the chain is an AnyTrust (DAC) chain (`true`) or a standard Rollup (`false`). | +| `ARB_OS_VERSION` | The version of ArbOS to use for the genesis block. | +| `CHAIN_OWNER` | The address that will have administrative ownership of the deployed chain. | +| `L1_BASE_FEE` | The initial L1 gas price (in Wei) used to calibrate the chain's birth. | +| `NITRO_NODE_IMAGE` | The Nitro node docker image used for hashing and node operations. | + +**Deployment Configuration (Optional)** +Only required if you choose to deploy the rollup to the parent chain in Step 3. +| Variable | Description | +| :--- | :--- | +| `DEPLOYER_PRIVATE_KEY` | Private key of the account responsible for the rollup deployment transactions. | +| `BATCH_POSTER_PRIVATE_KEY` | Private key for the Sequencer's batch-posting address. | +| `VALIDATOR_PRIVATE_KEY` | Private key for the Validator/Staker address. | +| `PARENT_CHAIN_RPC` | RPC endpoint for the parent chain (e.g., Arbitrum Sepolia or Ethereum). | + +#### Execution steps: + +1. **Prepare the environment** \ + From the root repository, install dependencies and navigate to the generator directory. + + ```bash + yarn install && yarn build + + cd examples/generate-genesis-file && cp .env.example .env + ``` + +2. **Generate Genesis** \ + Ensure your .env is configured (see reference above) and run the dev script. + `bash +yarn dev +` + :::tip Configuration + Double-check that your .env values match your intended chain specs before running the script. + ::: +3. **[Optional] Create rollup** \ + After generating the `genesis.json` file, the SDK provides an option to deploy your rollup. Follow the prompts to continue or exit the process and deploy the rollup later. + ### Use via `genesis-file-generator` tool -- **Prepare the genesis state:** Use the [genesis-file-generator tool](https://github.com/OffchainLabs/genesis-file-generator), to generate a standard `genesis.json` file with a set of pre-deploy contracts. During this process, you can use the following flags to customize your state: - - `--custom-alloc-account-file` – path to a JSON file containing your own account balances, contract bytecodes, and storage slots. - - `--not-load-default-predeploys` – use this flag if you want to skip the standard set of Orbit predeployed contracts and start with a clean slate. - - `--custom-serializedChainConfig` – use this flag to provide your own minified/serialized chain configuration string. +#### Configuration Reference + +**Environment Variables (.env)** \ +These parameters define the identity of your chain. +| Variable | Description | +| :--- | :--- | +| `CHAIN_ID` | The unique numeric identifier for your new chain. | +| `IS_ANYTRUST` | Whether the chain is an AnyTrust (DAC) chain (`true`) or a standard Rollup (`false`). | +| `ARB_OS_VERSION` | The version of ArbOS to use for the genesis block. | +| `CHAIN_OWNER` | The address that will have administrative ownership of the deployed chain. | +| `L1_BASE_FEE` | The initial L1 gas price (in Wei) used to calibrate the chain's birth. | +| `NITRO_NODE_IMAGE` | The Nitro node Docker image used for hashing and node operations. | +| `CUSTOM_ALLOC_ACCOUNT_FILE` | _(Optional)_ Path to a JSON file containing your own account balances, contract bytecodes, and storage slots. The file should be in the standard Geth `alloc` format. | +| `ENABLE_NATIVE_TOKEN_SUPPLY` | _(Optional)_ Set to `true` if you want to launch your chain with native interop tokens as [gas token with mint / burn enabled](/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-mint-burn) via third-party protocols. | +| `LOAD_DEFAULT_PREDEPLOYS` | _(Optional)_ Set to `false` if you don't want the default predeploys. By default the value for this variable is considered as `true`. | +| `ENABLE_TRANSACTION_FILTERING` | _(Optional)_ Set to `true` if you want to launch your chain with protocol-level transaction filtering for regulatory or compliance purposes. | + +#### Execution Process + +- **Prepare the genesis state:** Use the [genesis-file-generator tool](https://github.com/OffchainLabs/genesis-file-generator), to generate a standard `genesis.json` file with a set of pre-deploy contracts. + - Set up the `.env` with the required parameters + - Post setting up the evnironment variables, run the script. The script will generate the file under `./genesis` folder. + ```bash + ./generate.sh > genesis/genesis.json + ``` - You can also generate your own genesis.json file, but carefully read [this notice](https://github.com/OffchainLabs/genesis-file-generator#exclamation-important-note-about-the-chain-config-property) before proceeding with the next steps. -- **Generate required hashes:** After the genesis.json file is created, use [nitro’s genesis-generator tool](https://github.com/OffchainLabs/nitro/blob/v3.9.2/cmd/genesis-generator/genesis-generator.go) to obtain the genesis blockhash and sendRoot hash. -- **Deploy the rollup:** use the `blockhash` and `sendRoot` in the chain SDK. The SDK will use these to generate the `assertion_hash` needed to register your rollup's core smart contracts on the parent chain. +- **Generate required hashes:** After the genesis.json file is created, run the nitro container to compute the genesis block hash with `genesis-generator` entrypoint: + + ```bash + source .env + + docker run --rm \ + -v "$(pwd)/genesis":/data/genesisDir \ + --entrypoint genesis-generator \ + "$NITRO_NODE_IMAGE" \ + --genesis-json-file /data/genesisDir/genesis.json \ + --initial-l1-base-fee "$L1_BASE_FEE" + ``` + + This bind-mounts the current directory into the container so it can read the genesis.json file generated in the previous step, and outputs the genesis block hash and sendRoot hash. The block hash and sendRoot hash will be logged as: + + ```bash + genesis-hash-calculator | BlockHash: 0xd636d2cae7a75bf41f471639f1cbf98fe2a24216147792510e664a65496f27ed, SendRoot: 0x0000000000000000000000000000000000000000000000000000000000000000, Batch: 1, PosInBatch: 0 + ``` + +- **Deploy the rollup:** use the `blockhash`, `sendRoot`, `Batch` and `PosInBatch` in the chain SDK. The SDK will use these to generate the `assertion_hash` needed to register your rollup's core smart contracts on the parent chain. + ```javascript + const genesisAssertionState = { + globalState: { + bytes32Vals: [genesisBlockHash as `0x${string}`, sendRootHash as `0x${string}`] as [ + `0x${string}`, + `0x${string}`, + ], + // Set inbox position to 1 + u64Vals: [1n, 0n] as [bigint, bigint], + }, + machineStatus: 1, // FINISHED + endHistoryRoot: toHex(0, { size: 32 }), + }; + ``` - **Configure and launch your node:** set up your node as usual, but include the following properties to point to your custom state: - `--init.genesis-json-file=/path/to/genesis.json` - path to your custom `genesis.json` file - - `--chain.initial-l1base-fee=[Price]` – input the gas price from the L1 block where your rollup creation transaction was accepted. - -**Start your chain** with the correct preloaded state. +- **Start your chain** with the correct preloaded state. ## Pre-deployed Contracts Registry From b90500bd3eed39d30e8c353a535ae56e775d7418 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Wed, 11 Mar 2026 19:47:11 +0800 Subject: [PATCH 5/9] add new column for default env var --- .../common/use-a-custom-genesis.mdx | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx index 9eda846af7..a7a4cc9d70 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx @@ -100,18 +100,18 @@ yarn dev **Environment Variables (.env)** \ These parameters define the identity of your chain. -| Variable | Description | -| :--- | :--- | -| `CHAIN_ID` | The unique numeric identifier for your new chain. | -| `IS_ANYTRUST` | Whether the chain is an AnyTrust (DAC) chain (`true`) or a standard Rollup (`false`). | -| `ARB_OS_VERSION` | The version of ArbOS to use for the genesis block. | -| `CHAIN_OWNER` | The address that will have administrative ownership of the deployed chain. | -| `L1_BASE_FEE` | The initial L1 gas price (in Wei) used to calibrate the chain's birth. | -| `NITRO_NODE_IMAGE` | The Nitro node Docker image used for hashing and node operations. | -| `CUSTOM_ALLOC_ACCOUNT_FILE` | _(Optional)_ Path to a JSON file containing your own account balances, contract bytecodes, and storage slots. The file should be in the standard Geth `alloc` format. | -| `ENABLE_NATIVE_TOKEN_SUPPLY` | _(Optional)_ Set to `true` if you want to launch your chain with native interop tokens as [gas token with mint / burn enabled](/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-mint-burn) via third-party protocols. | -| `LOAD_DEFAULT_PREDEPLOYS` | _(Optional)_ Set to `false` if you don't want the default predeploys. By default the value for this variable is considered as `true`. | -| `ENABLE_TRANSACTION_FILTERING` | _(Optional)_ Set to `true` if you want to launch your chain with protocol-level transaction filtering for regulatory or compliance purposes. | +| Variable | Description | Default | +| :--- | :--- | :--- | +| `CHAIN_ID` | The unique numeric identifier for your new chain. | `31337` | +| `IS_ANYTRUST` | Whether the chain is an AnyTrust (DAC) chain (`true`) or a standard Rollup (`false`). | `false` | +| `ARBOS_VERSION` | The version of ArbOS to use for the genesis block. | `51` | +| `CHAIN_OWNER` | The address that will have administrative ownership of the deployed chain. | — | +| `L1_BASE_FEE` | The initial L1 gas price (in Wei) used to calibrate the chain's birth. | `1000000000` (1 gwei) | +| `NITRO_NODE_IMAGE` | The Nitro node Docker image used for hashing and node operations. | — | +| `CUSTOM_ALLOC_ACCOUNT_FILE` | _(Optional)_ Path to a JSON file containing your own account balances, contract bytecodes, and storage slots. The file should be in the standard Geth `alloc` format. | `""` (empty) | +| `ENABLE_NATIVE_TOKEN_SUPPLY` | _(Optional)_ Set to `true` if you want to launch your chain with native interop tokens as [gas token with mint / burn enabled](/launch-arbitrum-chain/features/common/gas-and-fees/choose-native-mint-burn) via third-party protocols. | `false` | +| `LOAD_DEFAULT_PREDEPLOYS` | _(Optional)_ Set to `false` if you don't want the default predeploys. | `true` | +| `ENABLE_TRANSACTION_FILTERING` | _(Optional)_ Set to `true` if you want to launch your chain with protocol-level transaction filtering for regulatory or compliance purposes. | `false` | #### Execution Process From ea7764a33024bb292db338ce7ba7e0ef670670b7 Mon Sep 17 00:00:00 2001 From: Abhishek Date: Wed, 11 Mar 2026 17:31:39 +0530 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../02-configure-your-chain/common/use-a-custom-genesis.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx index a7a4cc9d70..ab0d476136 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx @@ -41,7 +41,7 @@ You can use the feature via the SDK or by using the `genesis-file-generator` too ### Use via chain SDK :::caution -The feature is supported in chain SDK versions xx.xx and above. Chain SDK only allows the standard `genesis.json` creation which contains the predeploy contracts. In case you want to customize the `genesis.json` file or pass accounts / custom chain config, you should use the `genesis-generator-tool` for using the feature. +The feature is supported in chain SDK versions xx.xx and above. Chain SDK only allows the standard `genesis.json` creation which contains the predeploy contracts. In case you want to customize the `genesis.json` file or pass accounts / custom chain config, you should use the `genesis-file-generator` for using the feature. ::: The chain SDK provides an automated script that handles the entire lifecycle: building the genesis state, calculating `blockhash` and `sendRoot` hash, and creating the rollup. From d0359d434adfcd0cbccd8f1ccffc81a528b8a039 Mon Sep 17 00:00:00 2001 From: asomani-ocl Date: Wed, 11 Mar 2026 17:31:49 +0530 Subject: [PATCH 7/9] minor fix for new line --- .../02-configure-your-chain/common/use-a-custom-genesis.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx index a7a4cc9d70..7e629a301d 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx @@ -63,7 +63,7 @@ Required to generate the `genesis.json` file. | `L1_BASE_FEE` | The initial L1 gas price (in Wei) used to calibrate the chain's birth. | | `NITRO_NODE_IMAGE` | The Nitro node docker image used for hashing and node operations. | -**Deployment Configuration (Optional)** +**Deployment Configuration (Optional)** \ Only required if you choose to deploy the rollup to the parent chain in Step 3. | Variable | Description | | :--- | :--- | From 15c1cfca50148b0465e6479958e96d1688628162 Mon Sep 17 00:00:00 2001 From: asomani-ocl Date: Mon, 6 Apr 2026 15:59:48 +0530 Subject: [PATCH 8/9] updating docs to use public docker image for genesis generation --- .../common/use-a-custom-genesis.mdx | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx index 92cbc44c22..8d297d4d8c 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx @@ -36,7 +36,7 @@ This feature allows you to initialize a new blockchain with a customized startin ## **How to use this feature?** -You can use the feature via the SDK or by using the `genesis-file-generator` tool. +You can use the feature via the SDK or by using the [genesis-file-generator](https://github.com/OffchainLabs/genesis-file-generator) tool. ### Use via chain SDK @@ -94,7 +94,7 @@ yarn dev 3. **[Optional] Create rollup** \ After generating the `genesis.json` file, the SDK provides an option to deploy your rollup. Follow the prompts to continue or exit the process and deploy the rollup later. -### Use via `genesis-file-generator` tool +### Use via [genesis-file-generator](https://github.com/OffchainLabs/genesis-file-generator) tool #### Configuration Reference @@ -115,13 +115,22 @@ These parameters define the identity of your chain. #### Execution Process -- **Prepare the genesis state:** Use the [genesis-file-generator tool](https://github.com/OffchainLabs/genesis-file-generator), to generate a standard `genesis.json` file with a set of pre-deploy contracts. +- **Prepare the genesis state:** + - Set up the `.env` with the required parameters - - Post setting up the evnironment variables, run the script. The script will generate the file under `./genesis` folder. + - Run the [offchainlabs/genesis-file-generator](https://hub.docker.com/r/offchainlabs/genesis-file-generator/tags) docker image to generate `genesis.json` file with the required pre-deployed contracts and additional configs. + ```bash - ./generate.sh > genesis/genesis.json + mkdir -p genesis + + docker run --rm \ + --env-file .env \ + -v "$(pwd)/genesis":/app/genesis \ + offchainlabs/genesis-file-generator:latest ``` + - You can also generate your own genesis.json file, but carefully read [this notice](https://github.com/OffchainLabs/genesis-file-generator#exclamation-important-note-about-the-chain-config-property) before proceeding with the next steps. + - **Generate required hashes:** After the genesis.json file is created, run the nitro container to compute the genesis block hash with `genesis-generator` entrypoint: ```bash From be14e20629225116d6fec8819260810d5204219a Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 16 Apr 2026 12:37:37 -0500 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Jason-W123 <147362502+Jason-W123@users.noreply.github.com> --- .../02-configure-your-chain/common/use-a-custom-genesis.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx index 8d297d4d8c..7290bdbb15 100644 --- a/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/use-a-custom-genesis.mdx @@ -126,7 +126,7 @@ These parameters define the identity of your chain. docker run --rm \ --env-file .env \ -v "$(pwd)/genesis":/app/genesis \ - offchainlabs/genesis-file-generator:latest + offchainlabs/genesis-file-generator:v0.0.1-afad8d8 ``` - You can also generate your own genesis.json file, but carefully read [this notice](https://github.com/OffchainLabs/genesis-file-generator#exclamation-important-note-about-the-chain-config-property) before proceeding with the next steps. @@ -141,7 +141,6 @@ These parameters define the identity of your chain. --entrypoint genesis-generator \ "$NITRO_NODE_IMAGE" \ --genesis-json-file /data/genesisDir/genesis.json \ - --initial-l1-base-fee "$L1_BASE_FEE" ``` This bind-mounts the current directory into the container so it can read the genesis.json file generated in the previous step, and outputs the genesis block hash and sendRoot hash. The block hash and sendRoot hash will be logged as: