Running a Local Node

Overview

This guide explains how to set up and run a local Buburuza node in --dev mode. This mode is ideal for developers who want to quickly test smart contracts or blockchain modules on a single local node, without setting up the full parent–child chain infrastructure.

The --dev mode provides a lightweight and fast setup, making it perfect for rapid development, testing, and debugging.

If you require advanced functionality—such as cross-layer communication, integration with external rollups, or full parent/child chain simulation—then you should use the buburuza-testnode setup. That configuration allows you to simulate a complete L2/L3 environment, which is essential for testing interoperability or bridge-based operations.

However, for most local contract or chain logic testing, Buburuza’s --dev mode offers the simplest and most efficient development environment.

Prerequisites

Before you begin, ensure the following are installed and running on your machine:

  • Docker Required to run the Buburuza dev node in a container. 👉 Install Docker

  • cast (Foundry tool) Used to interact with Ethereum-compatible contracts. 👉 Install Foundry

  • jq A lightweight JSON parser used in deployment scripts. 👉 Install jq

Clone the Buburuza Dev Node Repository

git clone https://github.com/BuburuzaChain/buburuza-devnode.git
cd buburuza-devnode

Run the Dev Node Script

Run the provided script to start the Buburuza dev node, deploy the Cache Manager contract, and register it for contract execution:

This script will:

  1. Start the Buburuza dev node in a Docker container.

  2. Deploy the Buburuza Cache Manager contract locally.

  3. Register it as the WASM cache manager for contract execution.

Default Development Account

In --dev mode, the script uses a pre-funded development account. This account is automatically funded with native BUBU tokens and can be used to deploy contracts, interact with the chain, and manage chain settings.

  • Address: 0x3f1Eae7D46d88F08fc2F8ed27FCb2AB183EB2d0E

  • Private Key: 0xb6b15c8cb491557369f3c7d2c287b053eb229daa9c22138887752191c9520659

⚠️ You do not need to manually set up keys unless you want to use your own wallet.

Chain Ownership in Dev Mode

In Buburuza’s --dev mode, the default chain owner is set to: 0x0000000000000000000000000000000000000000

Ownership can be claimed using the BubuDebug precompile, which exposes the becomeChainOwner() function. This function lets you assume full ownership of the local chain instance.

Chain ownership enables administrative functions such as:

  • Adding or removing other chain owners

  • Adjusting gas pricing parameters

  • Managing network and infrastructure fee accounts

  • Modifying computational limits and gas ceilings

The setup script automatically assigns chain ownership to the default dev account before registering the Cache Manager.

Example command used internally by the script:

After Setup

Once the script finishes, you’ll have a fully operational Buburuza local dev node, pre-configured with:

  • The Cache Manager contract deployed and registered

  • A pre-funded dev account with ownership rights

  • RPC endpoint available at: http://127.0.0.1:8547

You can now start deploying and interacting with your Buburuza smart contracts, test chain logic, or integrate it with your dApps locally.

This setup is particularly useful for:

  • Testing Stylus-like WASM contracts

  • Validating gas optimizations

  • Experimenting with L3 configurations or rollup parameters

  • Local development before deploying to testnet or mainnet

PreviousSetting up environmentNextSmart Contract Deployment

Last updated