Ctrlk
AI Agent Resources
For the complete documentation index, see llms.txt. This page is also available as Markdown.

CLI

Deploy and manage L3 chains using the ADI CLI

The ADI CLI is a Rust-based tool that manages the full lifecycle of L3 chain deployment. It runs all operations inside pre-built Docker toolkit containers (zkstack, foundry-zksync, era-contracts) and outputs the resulting state files and generated wallets to your host machine.

Source: ADI-Foundation-Labs/ADI-CLI

Prerequisites

Requirement
Details

Docker

Running daemon. The CLI pulls and runs toolkit images automatically

Rust

Install via rustup

Funded wallet

~270 ADI tokens on the settlement layer for deployment gas costs. Testnet faucet: faucet.ab.testnet.adifoundation.ai

Installation

cargo install --git https://github.com/ADI-Foundation-Labs/ADI-CLI

Verify the installation:

adi version

Optionally generate shell completions:

mkdir -p ~/.oh-my-zsh/completions
adi completions zsh > ~/.oh-my-zsh/completions/_adi

Restart your shell to activate:

source ~/.zshrc

Configuration

The CLI reads configuration from a YAML file. Default location is ~/.adi.yml.

Override the config path with the --config flag or ADI_CONFIG environment variable.

Minimal Config

protocol_version determines which Docker toolkit image the CLI uses. Each protocol version is tied to a specific server version (e.g., protocol v0.30.1 works with server v13.1.0-b1).

If base_token_address is omitted, ADI is the gas token. You cannot change this after deployment. To use a custom token, set base_token_address to your ERC20 address on the settlement layer before adi init.

Wallet funding amounts and the funder key are not required in the config — they can be provided via CLI flags or environment variables during adi deploy. The only required config fields are the ecosystem definition and chain parameters.

Key Options

Option
Scope
Description

base_token_address

chain

Custom Gas Token (CGT) contract address on the settlement layer

governor_cgt_units

funding

Amount of CGT to fund the governor wallet

operators.operator

chain/global

Address for batch commit/revert roles

operators.prove_operator

chain/global

Address for proof submission

operators.execute_operator

chain/global

Address for batch execution

ownership.new_owner

ecosystem/chain

Transfer ownership to this address after deploy

ownership.private_key

ecosystem/chain

If provided, ownership is accepted automatically

gas_multiplier

global

Gas price buffer percentage (default: 200)

Set the funder wallet private key via environment variable:

Never put private keys directly in the config file. Use ADI_FUNDER_KEY for the funder and ownership.private_key only when automatic acceptance is needed.

For the full annotated config, environment variables, and S3 state sync, see the CLI Configuration Reference.

Ownership Transfer

When ownership.new_owner is set:

  • Address only — ownership is transferred after deployment. The new owner must run adi accept to complete the transfer.

  • Address + private_key — ownership is transferred and accepted automatically during deployment.

Verify the merged configuration:

Deployment Workflow

1. Initialize

The init command creates the ecosystem and chain configuration. It spins up a Docker container, generates wallets and configs inside it, then drops the resulting state files to your host.

Flag
Description

--chain

Select chain from config chains[] by name

--force

Overwrite existing ecosystem state

--yes

Skip confirmation prompts

If you have a single ecosystem and chain configured, the CLI selects them automatically. Otherwise it will prompt you to choose. You can also specify --chain explicitly.

Example output:

After init, state is written to ~/.adi_cli/state/<ecosystem>/:

Wallets are plain EOAs. You can reuse operator keys across L3 deployments by copying wallets.yaml and secrets.yaml from a previous deployment. Do not reuse genesis.yaml or contracts.yaml. Those files are chain-specific.

The generated genesis.json used by the server includes l1_chain_id for your settlement layer. For L3s on ADI, that is 36900 on mainnet or 99999 on testnet. adi init sets this automatically. Do not edit it manually.

2. Deploy

The deploy command funds the generated wallets and deploys all contracts to the settlement layer (L2).

The funder private key can be provided in three ways (in priority order): --funder-key flag, ADI_FUNDER_KEY env var, or funding.funder_key in config.

Example output:

This command:

  1. Connects to the settlement layer and checks wallet balances

  2. Funds deployer, governor, and operator wallets from the funder

  3. Deploys ecosystem and chain contracts (Bridgehub, STM, Diamond Proxy)

  4. Configures validator roles on chain contracts

  5. Handles ownership transfer if configured

State

All state lives in ~/.adi_cli/state/. This directory contains wallets (with private keys), deployed contract addresses, and chain configurations. Back it up.

State can optionally sync to S3-compatible storage with adi state sync / adi state restore. See the CLI Configuration Reference for details.

Next Steps

Once contracts are deployed, set up the chain infrastructure (sequencer, prover, explorer, bridge) using Docker Compose:

Run a Rollup with Docker Compose

Additional CLI commands for post-deployment:

Command
Purpose

adi verify

Verify deployed contracts on block explorers

adi server-params

Output server parameters for docker-compose configuration

adi owners

Display current contract owners

adi transfer

Transfer ownership to a new address

adi upgrade

Upgrade contracts to a new protocol version

PreviousL3 ChainsNextRun a Rollup with Docker Compose

Last updated