From 3151bc05b838bb099130cfb021f37009c4423fb8 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Mon, 22 Sep 2025 17:23:03 +0800 Subject: [PATCH 1/6] add genesis json docs --- .../deploy-chain-with-geneis-json.mdx | 236 ++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx diff --git a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx new file mode 100644 index 0000000000..46200ac547 --- /dev/null +++ b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx @@ -0,0 +1,236 @@ +# Deploying Arbitrum Orbit Chains Using Genesis Configuration + +## Overview + +This guide demonstrates how to deploy an Arbitrum Orbit chain using a custom genesis.json configuration with the orbit-cli-tool and nitro's genesis generator. This approach allows you to deploy chains with pre-configured accounts, balances, and smart contracts in the genesis block. + +The deployment workflow consists of three main steps: + +1. **Genesis Generation**: Using orbit-cli-tool (with orbit-sdk) to generate `genesis.json` +2. **Assertion Hash Calculation**: Using nitro's genesis generator to calculate the assertion hash +3. **Contract Deployment**: Using orbit-cli-tool to deploy rollup contracts + +## Prerequisites + +- Node.js and npm/yarn installed +- orbit-cli-tool repository cloned and configured +- nitro repository with genesis-generator compiled +- Access to Arbitrum Sepolia testnet for rollup deployment +- Custom genesis configuration requirements (accounts, balances, contracts) + +## Step 1: Generate Genesis Configuration + +This step creates a custom genesis.json file that includes your specific chain parameters, account allocations, and any pre-deployed contracts needed for your Orbit chain. + +### Setup + +Navigate to your orbit-cli-tool directory and install dependencies: + +```bash +cd orbit-cli-tool +npm install +# or +yarn install +``` + +### Create Account Allocations (Optional) + +If you need to allocate funds or deploy contracts in the genesis block, create an `alloc.json` file: + +```json +{ + "0x0000000000000000000000000000000000007070": { + "balance": "1000000000000000000000", + "nonce": "1", + "code": "0x608060405234801561000f575f80fd5b...", + "storage": { + "0x0000000000000000000000000000000000000000000000000000000000000404": "8ce8c13d816fe6daf12d6fd9e4952e1fc88850af0001" + } + } +} +``` + +**Note**: Account addresses can be specified with or without the `0x` prefix. + +### Generate Genesis File + +Run the genesis generation command: + +```bash +node index.js saveGenesis +``` + +This command performs the following actions: + +- Generates a random chain ID for your Orbit chain +- Creates chain configuration with Arbitrum-specific parameters +- Loads account allocations from `alloc.json` (if present) +- Outputs a properly formatted `genesis.json` file + +The generated `genesis.json` follows a specific format where: + +- The `config` field is compact (single line) for Go tool compatibility +- Other fields use 2-space indentation for readability + +### Verify Genesis File + +After generation, verify that your `genesis.json` contains: + +- Valid chain ID +- Proper chain configuration parameters +- Account allocations (if specified) +- Correct formatting for subsequent processing + +## Step 2: Calculate Genesis Block Hash and Assertion Hash + +Using nitro's genesis generator, we calculate the hashes required for rollup deployment. The genesis generator processes your custom genesis.json and computes the assertion hash that will be used in the rollup contracts. + +### Calculate Genesis Block Hash + +You can calculate the genesis block hash using either a local build or Docker. Choose the method that best fits your environment. + +#### Method 1: Using Local Build + +**Step 1: Install Prerequisites** + +Visit the [official nitro build documentation](https://docs.arbitrum.io/run-arbitrum-node/nitro/build-nitro-locally) to install the required **prerequisite tools**. + +**Step 2: Build Genesis Generator** + +Clone the nitro repository and build the genesis generator: + +```bash +cd /path/to/nitro +make target/bin/genesis-generator +``` + +**Step 3: Calculate Hash** + +Run the genesis generator with your genesis.json file: + +```bash +./target/bin/genesis-generator --genesis-json-file ./genesis.json --initial-l1-base-fee {Your_estimate_parent_chain_gas_price} +``` + +#### Method 2: Using Docker + +This method is simpler and doesn't require building nitro locally. + +```bash +docker run -v $(pwd):/data/genesisDir --entrypoint genesis-generator offchainlabs/nitro-node:v3.7.2-42be4fe --genesis-json-file /data/genesisDir/genesis.json --initial-l1-base-fee {Your_estimate_parent_chain_gas_price} +``` + +**Note**: Replace `{Your_estimate_parent_chain_gas_price}` with your estimated parent chain (Arbitrum Sepolia) gas price in wei (e.g., `1000000000` for 1 gwei). + +#### Expected Output + +After running either method, you will see output similar to: + +``` +BlockHash: 0x6d429f9c36b7fd56c4296b5e1f963e465179d170a3d64be49b17c0af59c95794, SendRoot: 0xf5cac8d69a469505fbe822c19c6b534ded192b9db3cf6bd9063dc6dcb10212d6, Batch: 1, PosInBatch: 0 +``` + +**Save the BlockHash**: Copy the `BlockHash` value (e.g., `0x6d429f9c36b7fd56c4296b5e1f963e465179d170a3d64be49b17c0af59c95794`) as you'll need it for the rollup deployment step. + +#### ⚠️ Critical Requirement + +**The L1 gas price used in `--initial-l1-base-fee` MUST be exactly identical to the actual gas price when deploying the rollup contracts.** Any difference will cause deployment failure. + +**Important Steps**: + +- Record the exact gas price value used in `--initial-l1-base-fee` +- When deploying the rollup, ensure the gas price for the deployment transaction is exactly the same +- If gas prices have changed at all, you must regenerate the genesis block hash with the current gas price + +## Step 3: Deploy Rollup Contracts + +The final step involves deploying the actual rollup contracts to Arbitrum Sepolia using the calculated genesis block hash. + +### Deploy Rollup + +Execute the rollup creation command with your genesis block hash: + +```bash +node index.js createRollup +``` + +Replace `` with the BlockHash value obtained from step 2. + +**⚠️ Critical Requirement**: The gas price used for the rollup deployment transaction MUST be exactly identical to the `--initial-l1-base-fee` value used when generating the genesis block hash. Any difference will cause deployment failure. If gas prices have changed at all, regenerate the genesis block hash first. + +### Deployment Process + +The rollup deployment will: + +- Read the previously generated `genesis.json` +- Extract chain configuration and chain ID +- Deploy rollup contracts to Arbitrum Sepolia testnet + +## Configuration Reference + +### Genesis Configuration Structure + +```json +{ + "config": { + "chainId": 123, + "homesteadBlock": 0, + "daoForkBlock": null, + "daoForkSupport": true, + "eip150Block": 0, + "eip150Hash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "eip155Block": 0, + "eip158Block": 0, + "byzantiumBlock": 0, + "constantinopleBlock": 0, + "petersburgBlock": 0, + "istanbulBlock": 0, + "muirGlacierBlock": 0, + "berlinBlock": 0, + "londonBlock": 0, + "clique": { "period": 0, "epoch": 0 }, + "arbitrum": { + "EnableArbOS": true, + "AllowDebugPrecompiles": false, + "DataAvailabilityCommittee": false, + "InitialArbOSVersion": 40, + "InitialChainOwner": "0xYour_Chain_Owner_Address", + "GenesisBlockNum": 0, + "MaxCodeSize": 24576, + "MaxInitCodeSize": 49152 + } + }, + "nonce": "0x0", + "timestamp": "0x0", + "extraData": "0x", + "gasLimit": "0x1c9c380", + "difficulty": "0x1", + "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000", + "coinbase": "0x0000000000000000000000000000000000000000", + "alloc": { + // Account allocations from alloc.json + } +} +``` + +## Troubleshooting + +### Common Issues + +**Genesis Generation Fails** + +- Verify all dependencies are installed +- Check that `alloc.json` has valid JSON format +- Ensure sufficient disk space for file generation + +**Genesis Generator Issues** + +- Confirm nitro's genesis generator is properly compiled +- Verify genesis.json format matches expected input +- Check for any missing dependencies in the nitro environment + +**Rollup Deployment Fails** + +- Verify genesis block hash is correct and properly formatted +- Ensure sufficient funds for gas fees on Arbitrum Sepolia +- Check network connectivity and RPC endpoint availability From dc7e0cf016f5db9846abe23b0b1c79511df485a8 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Mon, 22 Sep 2025 17:25:07 +0800 Subject: [PATCH 2/6] change reference --- docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx index 46200ac547..45039493b5 100644 --- a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx +++ b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx @@ -93,7 +93,7 @@ You can calculate the genesis block hash using either a local build or Docker. C **Step 1: Install Prerequisites** -Visit the [official nitro build documentation](https://docs.arbitrum.io/run-arbitrum-node/nitro/build-nitro-locally) to install the required **prerequisite tools**. +Visit the [official nitro build documentation](/run-arbitrum-node/nitro/build-nitro-locally) to install the required **prerequisite tools**. **Step 2: Build Genesis Generator** From 7a61ae2fa98a712c42d9720668c2309c8e94b546 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Mon, 22 Sep 2025 17:26:28 +0800 Subject: [PATCH 3/6] use arbitrum chains as title name --- docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx index 45039493b5..fbfe01386b 100644 --- a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx +++ b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx @@ -1,4 +1,4 @@ -# Deploying Arbitrum Orbit Chains Using Genesis Configuration +# Deploying Arbitrum Chains Using Genesis Configuration ## Overview From 943b890a0ba7d9f4cad486d2e0f383f1dfc628a0 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Mon, 22 Sep 2025 17:41:59 +0800 Subject: [PATCH 4/6] fix --- docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx index fbfe01386b..764d624904 100644 --- a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx +++ b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx @@ -14,8 +14,7 @@ The deployment workflow consists of three main steps: - Node.js and npm/yarn installed - orbit-cli-tool repository cloned and configured -- nitro repository with genesis-generator compiled -- Access to Arbitrum Sepolia testnet for rollup deployment +- nitro repository with genesis-generator compiled (If compiling locally, follow the [official nitro build documentation](/run-arbitrum-node/nitro/build-nitro-locally)) - Custom genesis configuration requirements (accounts, balances, contracts) ## Step 1: Generate Genesis Configuration From 49308572c75479774b2ab466a519dbfe4761a19f Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Mon, 22 Sep 2025 17:48:21 +0800 Subject: [PATCH 5/6] add docker refer --- docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx index 764d624904..6d26b2fdbf 100644 --- a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx +++ b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx @@ -15,6 +15,7 @@ The deployment workflow consists of three main steps: - Node.js and npm/yarn installed - orbit-cli-tool repository cloned and configured - nitro repository with genesis-generator compiled (If compiling locally, follow the [official nitro build documentation](/run-arbitrum-node/nitro/build-nitro-locally)) +- Docker installed (If not compiling locally) - Custom genesis configuration requirements (accounts, balances, contracts) ## Step 1: Generate Genesis Configuration From a3dd6db41b3db6fe9dfe9236ed27c1abb62d118c Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Mon, 22 Sep 2025 17:52:31 +0800 Subject: [PATCH 6/6] remove unused lines --- .../deploy-chain-with-geneis-json.mdx | 22 ------------------- 1 file changed, 22 deletions(-) diff --git a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx index 6d26b2fdbf..cf4586dd2d 100644 --- a/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx +++ b/docs/launch-arbitrum-chain/deploy-chain-with-geneis-json.mdx @@ -212,25 +212,3 @@ The rollup deployment will: } } ``` - -## Troubleshooting - -### Common Issues - -**Genesis Generation Fails** - -- Verify all dependencies are installed -- Check that `alloc.json` has valid JSON format -- Ensure sufficient disk space for file generation - -**Genesis Generator Issues** - -- Confirm nitro's genesis generator is properly compiled -- Verify genesis.json format matches expected input -- Check for any missing dependencies in the nitro environment - -**Rollup Deployment Fails** - -- Verify genesis block hash is correct and properly formatted -- Ensure sufficient funds for gas fees on Arbitrum Sepolia -- Check network connectivity and RPC endpoint availability