Arbitrum Chain SDK

TypeScript SDK for building Arbitrum chains.

Installation

Make sure you are using Node.js v18 or greater.

pnpm add @arbitrum/chain-sdk viem@^1.20.0

Custom genesis generation

Genesis generation is intentionally not exposed as an SDK function: there is no generateGenesis export in @arbitrum/chain-sdk. The generateGenesis CLI command requires the external genesis-generator binary and @arbitrum/genesis-file-generator, which are bundled only in the Docker image and are not included in the SDK's npm package. Run this command using the Docker image.

See the custom genesis example to generate a genesis file with a custom allocation and save its block hash and send root.

CLI

The SDK ships a CLI that exposes its functions, workflows, and contract calls as subcommands. Each command takes a single JSON argument and prints a JSON result. Useful from shell scripts, CI, or any non-TypeScript caller.

Install

Install it globally from npm to put arbitrum-chain-sdk on your PATH:

npm i -g @arbitrum/chain-sdk
arbitrum-chain-sdk <command> '<json>'

Or run it without installing (append @<version> to pin a release):

npx @arbitrum/chain-sdk <command> '<json>'

Or pull the Docker image for a pinned, reproducible environment:

docker pull offchainlabs/arbitrum-chain-sdk:latest
docker run --rm offchainlabs/arbitrum-chain-sdk:latest <command> '<json>'

The examples below use the installed arbitrum-chain-sdk command. Under Docker, replace arbitrum-chain-sdk with docker run --rm offchainlabs/arbitrum-chain-sdk:latest.

Usage

arbitrum-chain-sdk <command> '<json>' [-o <path>]
arbitrum-chain-sdk <command> --schema   [-o <path>]

The JSON argument can be supplied three ways:

• As a literal: arbitrum-chain-sdk getValidators '{"rpcUrl":"...","chainId":42161,"rollup":"0x..."}'
• From a file: arbitrum-chain-sdk getValidators @input.json
• From stdin: cat input.json | arbitrum-chain-sdk getValidators -

JSON with comments and trailing commas (JSONC) is accepted.

Under Docker the file and stdin forms need extra flags: mount the working directory (-v "$(pwd):/work" -w /work) for @file, and add -i for stdin.

Flags:

• -o <path> — write the result to a file instead of stdout.
• --schema — print the input JSON Schema for the command and exit.

Discovering commands

Run the CLI with no command to print the full command list:

arbitrum-chain-sdk

Commands fall into three groups:

• SDK functions — direct wrappers around SDK exports (getValidators, createRollup, …).
• Workflows — multi-step orchestrations (deployParentChainContracts, deployNewChain, deployFullChain, transferOwnership, initializeTokenBridge).
• Contract calls — generic read/write/encode against a contract ABI (ArbOwner, Rollup@v3.2, Inbox, …). Versioned entries sit alongside an unversioned alias pointing at the current default.

To see the input shape for a command:

arbitrum-chain-sdk <command> --schema

Output

• stdout — the JSON result. BigInt values are serialized as decimal strings.
• stderr — SDK progress logs, validation errors, and stack traces.
• Exit code — 0 on success, 1 on any parse, validation, or runtime error.

Example

Build a Nitro chainConfig for a new Arbitrum chain. This is the first call in the deploy-a-new-chain flow — given a chain ID and the chain's initial owner, the SDK fills in the full config:

arbitrum-chain-sdk prepareChainConfig '{
  "chainId": 12345,
  "arbitrum": {
    "InitialChainOwner": "0x0000000000000000000000000000000000000001"
  }
}'

Development

Use Node.js 24 (nvm use) and pnpm 11.26.0, as pinned in .nvmrc and package.json. Install dependencies with pnpm install --frozen-lockfile.

Run integration tests

Clone the branch release of nitro-testnode, and run the testnode using the following arguments:

./test-node.bash --init --tokenbridge --l3node --l3-fee-token --l3-token-bridge

Then, run the integration tests:

pnpm test:integration

Publishing to npm

Manually update the version in src/package.json and commit the change. Then create and push a matching version tag from that commit:

git tag v0.28.0
git push origin v0.28.0

The publish-npm.yml workflow checks that the tag matches src/package.json, builds the SDK, and stages the package on npm. Stable tags such as v0.28.0 use the latest npm dist-tag. Prerelease tags must use vX.Y.Z-alpha.N, vX.Y.Z-beta.N, or vX.Y.Z-rc.N and use the corresponding alpha, beta, or rc npm dist-tag.

CI does not modify the package version or create or push commits or tags.

Examples

See examples.