Set Up Your Appchain - Initia Docs

Build an Appchain with Your AI Agent

Welcome to the hackathon! This guide will walk you through building an appchain from scratch. You’ll go from a simple idea to a functioning appchain and frontend efficiently.

Step 1: Prepare Your Workspace

Before installing tools or initializing your appchain, create a dedicated directory for your project. This keeps your configuration files, VM binaries, and smart contracts organized in one place. Run the following commands in your terminal:

mkdir my-initia-project
cd my-initia-project

Step 2: Install Your AI Skill

Your AI agent needs the Initia Appchain Dev skill to help you manage your appchain, write smart contracts, and build your frontend. Run the following command in your terminal:

npx skills add initia-labs/agent-skills

Step 3: Select an AI Agent

These guides assume you are using a code-aware AI agent that can access your project directory, read files, run commands, and help you edit code. Any equivalent tool is fine.

Terminal Agents (CLI)

AI-Powered IDEs

Keep your AI agent open in your project root so it can use your local context when you paste the prompts in this guide.

Recommended setup: Use two terminal tabs or a split-screen layout:

AI agent: For high-level tasks, contract generation, and troubleshooting.
Standard terminal: For interactive CLI commands like weave init and long-running builds.

Step 4: Select Your Track & VM

Before installing tools, decide what you want to build. This choice determines which Virtual Machine (VM) your AI agent will set up for you.

Track	Recommended VM	Reason
`Gaming / Consumer`	`Move`	Best for complex onchain logic and object-oriented assets.
`DeFi / Institutional`	`EVM` (Solidity)	Best for leveraging existing Ethereum tooling and libraries.
`AI / Tooling`	`Wasm` (Rust)	Best for backend-heavy apps, agents, and tooling.

If you are building for the AI track and want guidance on where AI should live in your architecture, see AI Track Guidance.

Step 5: Prerequisites Checklist

To ensure a smooth setup, verify you have the following system tools installed:

Docker Desktop: Required for running the bridge bots and relayer. Must be running.
Go (1.22+): Required to build the appchain binaries.
Track Specifics:
- Move: No extra tools required.
- EVM: Foundry (Forge) is recommended for contract development.
- Wasm: Rust & Cargo are required for contract development.

Step 6: AI-Powered Initia Tool Setup and Verification

Now, ask your AI agent to handle the Initia-specific tools. It will install the core CLIs (weave, initiad, jq), build your chosen VM binary (minitiad), and verify everything is in your PATH. Replace <MOVE / EVM / WASM> with your selected track from Step 4 (Move, EVM, or Wasm).

Prompt: Set up my environment

Using the `initia-appchain-dev` skill, please set up my environment for the <MOVE / EVM / WASM> track.

Verify Installation & PATH

After setup completes, your AI agent can verify the tools are accessible from anywhere on your system.

Prompt: Verify tool installation

Using the `initia-appchain-dev` skill, please verify that `initiad`, `weave`, and `minitiad` are properly installed and accessible in my PATH.

Step 7: Initial Setup With `weave init`

Your AI agent is your partner in this hackathon, but the weave CLI requires an interactive setup flow to prepare your environment and launch your appchain. You can run it whenever you need to initialize or reconfigure your setup.

Resetting Existing Local State: If you already ran weave init and want to create a new appchain, run the following commands first. This clears your existing local Initia, Minitia, OPinit, and relayer setup:

rm -rf ~/.weave ~/.initia ~/.minitia ~/.opinit
docker rm -f weave-relayer || true

Run the following command in your terminal:

weave init

Here’s a guide on how to navigate the interactive setup:

Foundation & Funding

Generate Gas Station Account

The Gas Station is an account on the Initia L1 that will fund your rollup’s infrastructure.Prompt:

How would you like to set up your Gas Station account?

Action: Select Generate new account (recommended).Result: You will see your new Gas Station Address. Copy this address.

Fund Your Gas Station Account

Action: Go to the Initia Testnet Faucet.Action: Paste your address and click Submit to receive testnet INIT tokens.Prompt:

Type `continue` to proceed.

Action: Type continue and press Enter.

Rollup Identity

Select Your Action

Prompt:

What do you want to do?

Action: Select Launch a new rollup.

Switching VMs? Reinstall the correct minitiad binary first (Step 6). If you have existing rollup data, type confirm when prompted to clean it and proceed.

Select L1 Network

Prompt:

Select the Initia L1 network

Action: Select Testnet (initiation-2).

Select Virtual Machine (VM)

Prompt:

Select the Virtual Machine (VM)

Action: Select your desired VM (e.g., Move).

Specify Rollup Chain ID

Prompt:

Specify rollup chain ID

Action: Enter a unique ID (e.g., mygame-1).

Save your Chain ID! You’ll need this unique identifier for your final submission.

Specify Rollup Gas Denom

Prompt:

Specify rollup gas denom

Action: Press Tab for default (umin) or enter your own.

Specify Rollup Node Moniker

Prompt:

Specify rollup node moniker

Action: Press Tab for default (operator).

Network & Infrastructure

Submission Interval

Prompt:

Specify OP bridge config: Submission Interval

Action: Press Tab for default (1m).

Finalization Period

Prompt:

Specify OP bridge config: Output Finalization Period

Action: Press Tab for default (168h).

Data Availability

Prompt:

Where should the rollup blocks data be submitted?

Action: Select Initia L1.

Enable Oracle Price Feed

Prompt:

Would you like to enable oracle price feed from L1?

Action: Select Enable.

Security & Genesis

Setup Method for System Keys

Prompt:

Select a setup method for the system keys

Action: Select Generate new system keys.

System Accounts Funding Option

Prompt:

Select system accounts funding option

Action: Select Use the default preset.

Specify Fee Whitelist Addresses

Prompt:

Specify fee whitelist addresses

Action: Press Enter to leave empty.

Add Gas Station Account to Genesis

Prompt:

Would you like to add the Gas Station account to genesis accounts?

Action: Select Yes.

Specify Genesis Balance

Prompt:

Specify the genesis balance for the Gas Station account

Action: Enter 1000000000000000000000000 (10^24). This ensures you have plenty of tokens for testing, especially for EVM.

Move Track Balance Limit: Use 10000000000000000000 (10^19) to avoid u64 overflows.

Add Additional Genesis Accounts

Prompt:

Would you like to add genesis accounts?

Action: Select No.

Launch

Verify System Keys & Continue

Prompt:

Type 'continue' to proceed.

Action: Type continue and press Enter.

Confirm Transactions

Prompt:

Confirm to proceed with signing and broadcasting the following transactions? [y]:

Action: Type y and press Enter.Your appchain will now launch and start producing blocks!

Step 8: Setup Interwoven Bots

To enable the Optimistic bridge and cross-chain communication (IBC) between Initia L1 and your appchain, you need to start the OPinit Executor and the IBC Relayer. These bots manage the cross-chain connectivity of your chain.

Prerequisite: Your appchain must be running before configuring these bots. Because weave init runs your chain in the background, you can continue using the same terminal window.

8.1 Start the OPinit Executor

The executor handles the submission of rollup data and bridge operations. Run the following command:

weave opinit init executor

Follow the interactive guide:

Use Detected Keys

Prompt:

Existing keys in config.json detected. Would you like to add these to the keyring before proceeding?

Action: Select Yes, use detected keys.

System Key for Oracle

Prompt:

Please select an option for the system key for Oracle Bridge Executor

Action: Select Generate new system key.

Pre-fill Data

Prompt:

Existing config.json detected. Would you like to use the data in this file to pre-fill some fields?

Action: Select Yes, prefill.

Listen Address

Prompt:

Specify listen address of the bot

Action: Press Tab to use localhost:3000 (ensure nothing else is running on this port).

Finalize Configuration

Action: Press Enter for L1 RPC, Chain ID, and Gas Denom. For Rollup RPC, press Tab to use http://localhost:26657.

Start the Bot

Once initialized, start the bot in the background:

weave opinit start executor -d

8.2 Start the IBC Relayer

The relayer enables asset transfers (like INIT) between the L1 and your appchain.

Docker Desktop must be running to launch the relayer.

Run the following command:

weave relayer init

Follow the interactive guide:

Select Rollup

Prompt:

Select the type of Interwoven rollup you want to relay

Action: Select Local Rollup (<YOUR_APPCHAIN_ID>).

Endpoints

Action: Press Tab for both RPC (http://localhost:26657) and REST (http://localhost:1317) endpoints.

Channel Method

Prompt:

Select method to set up IBC channels for the relayer

Action: Select Subscribe to only transfer and nft-transfer IBC Channels (minimal setup).

Select Channels

Prompt:

Select the IBC channels you would like to relay

Action: Press Space to select all (transfer and nft-transfer), then press Enter.

Challenger Key

Prompt:

Do you want to set up relayer with the challenger key

Action: Select Yes (recommended).

Start Relayer

Start the relayer process:

weave relayer start -d

You can view relayer logs at any time by running weave relayer log in your terminal.

Persistence After Restart: After restarting your computer, the relayer remains managed by Docker. As long as Docker Desktop is open, it should still be running. You still need to restart your rollup full node and executor:

weave rollup start -d

weave opinit start executor -d

Step 9: Final Key Setup

Why: The Gas Station account acts as your Universal Developer Key. Importing it allows you to sign transactions manually via the CLI, and it enables your AI co-pilot to deploy contracts and interact with your appchain. Action: Run these commands to import your account into both the L1 (initiad) and L2 (minitiad) keychains:

# Extract your mnemonic from the weave config
MNEMONIC=$(jq -r '.common.gas_station.mnemonic' ~/.weave/config.json)

# Import into initiad (L1)
initiad keys add gas-station --recover --keyring-backend test --coin-type 60 --key-type eth_secp256k1 --source <(echo -n "$MNEMONIC")

# Import into minitiad (L2)
minitiad keys add gas-station --recover --keyring-backend test --coin-type 60 --key-type eth_secp256k1 --source <(echo -n "$MNEMONIC")

Action: Verify the import by listing your keys to ensure gas-station appears in both:

# Verify L1 keys
initiad keys list --keyring-backend test

# Verify L2 keys
minitiad keys list --keyring-backend test

Production Security: This workflow is for rapid prototyping only.

Insecure Storage: config.json and --keyring-backend test are for convenience, not production.
Mainnet: Use secure keyrings (OS keychain, hardware wallet) and never store mnemonics in plaintext.
Best Practice: Use separate accounts for Gas Station, Validator, and Developer roles on Mainnet.

Step 10: Verifying Your Appchain

After completing the infrastructure setup, verify that everything is healthy.

Prompt: Verify my appchain is healthy

Using the `initia-appchain-dev` skill, please verify that my appchain, executor bot, and relayer are running and that my Gas Station account has a balance.

Step 11: Build Your App

Congratulations! You have successfully launched your first appchain. Next, head to the Builder Guide to select whether to build from scratch or start from a Blueprint, then build your app with AI, debug issues, and prepare your submission.

​Build an Appchain with Your AI Agent

​Step 1: Prepare Your Workspace

​Step 2: Install Your AI Skill

​Step 3: Select an AI Agent

​Terminal Agents (CLI)

​AI-Powered IDEs

​Step 4: Select Your Track & VM

​Step 5: Prerequisites Checklist

​Step 6: AI-Powered Initia Tool Setup and Verification

​Verify Installation & PATH

​Step 7: Initial Setup With weave init

​Generate Gas Station Account

​Fund Your Gas Station Account

​Select Your Action

​Select L1 Network

​Select Virtual Machine (VM)

​Specify Rollup Chain ID

​Specify Rollup Gas Denom

​Specify Rollup Node Moniker

​Submission Interval

​Finalization Period

​Data Availability

​Enable Oracle Price Feed

​Setup Method for System Keys

​System Accounts Funding Option

​Specify Fee Whitelist Addresses

​Add Gas Station Account to Genesis

​Specify Genesis Balance

​Add Additional Genesis Accounts

​Verify System Keys & Continue

​Confirm Transactions

​Step 8: Setup Interwoven Bots

​8.1 Start the OPinit Executor

​8.2 Start the IBC Relayer

​Step 9: Final Key Setup

​Step 10: Verifying Your Appchain

​Step 11: Build Your App

Build an Appchain with Your AI Agent

Step 1: Prepare Your Workspace

Step 2: Install Your AI Skill

Step 3: Select an AI Agent

Terminal Agents (CLI)

AI-Powered IDEs

Step 4: Select Your Track & VM

Step 5: Prerequisites Checklist

Step 6: AI-Powered Initia Tool Setup and Verification

Verify Installation & PATH

Step 7: Initial Setup With `weave init`

Generate Gas Station Account

Fund Your Gas Station Account

Select Your Action

Select L1 Network

Select Virtual Machine (VM)

Specify Rollup Chain ID

Specify Rollup Gas Denom

Specify Rollup Node Moniker

Submission Interval

Finalization Period

Data Availability

Enable Oracle Price Feed

Setup Method for System Keys

System Accounts Funding Option

Specify Fee Whitelist Addresses

Add Gas Station Account to Genesis

Specify Genesis Balance

Add Additional Genesis Accounts

Verify System Keys & Continue

Confirm Transactions

Step 8: Setup Interwoven Bots

8.1 Start the OPinit Executor

8.2 Start the IBC Relayer

Step 9: Final Key Setup

Step 10: Verifying Your Appchain

Step 11: Build Your App