Nibiru

Nibiru is a breakthrough Layer 1 blockchain and smart contract ecosystem providing superior throughput, improved security, and a high-performance EVM execution layer. Nibiru aims to be the most developer-friendly and user-friendly smart contract ecosystem, leading the charge toward mainstream Web3 adoption by innovating at each layer of the stack: dApp development, scalable blockchain data indexing, consensus optimizations, a comprehensive developer toolkit, and composability across multiple VMs.

Table of Contents:

• Documentation
• Community
• Nibiru Core Architecture
  • Execution Extensions
  • Auxiliary Modules
  • Consensus Engine
• Developing in this Codebase
  • Docker Development Environment
• How to Install Nibiru
• License

---

Documentation

• Nibiru Docs (nibiru.fi/docs): This is the best resource for comprehensive technical, conceptual, and product documentation on Nibiru.
• Complete Golang reference docs: (pkg.go.dev) For the blockchain implementation.
• Nibiru RPC Endpoints
• Core Tools and Language Clients

Community

If you have questions or concerns, feel free to connect with a developer or community member in the Nibiru Discord. We also have active communities on X and Telegram.

Nibiru Core Architecture

Execution Extensions

These sections of the codebase extend or augment core runtime behavior.

Module	Description
EVM	Implements Nibiru EVM, which manages an Ethereum Virtual Machine (EVM) state database and enables the execution of Ethereum smart contracts. Nibiru EVM is an extension of "geth" along with "web3" and "eth" JSON-RPC methods.
Wasm	Implements the execution environment for WebAssembly (WASM) smart contracts. CosmWasm smart contracts are Rust-based, Wasm smart contracts built for enhanced security, performance, and interoperability. See our CosmWasm sandbox monorepo (nibiru-wasm) for the protocol's core smart contracts.
Eth	Ethereum integration utilities: EVM JSON-RPC server (HTTP/WebSocket) and APIs (eth/net/web3/debug/txpool), EVM transaction indexer for fast lookups, EIP-155 chain IDs, and EIP-712 signing helpers. See also server for JSON-RPC bootstrap and config.
App	Core application logic including custom ante handlers for transaction preprocessing, gas management, signature verification, and EVM integration. Key features include oracle gas optimization, zero-gas actors, and enhanced security guards.
x/nutil	Helper and utility functions to be utilized by other x/ modules.

Auxiliary Modules

Module	Description
Devgas	The devgas module of Nibiru shares contract execution fees with smart contract developers. This aims to increase the adoption of Nibiru by offering CosmWasm smart contract developers a direct source of income based on usage.
Epochs	The epochs module allows other modules to set hooks to be called to execute code automatically on a period basis. For example, "once a week, starting at UTC-time = x". epochs creates a generalized epoch interface.
Inflation	Implements the tokenomics for Nibiru.
Oracle	Nibiru accurately prices assets using a native, system of decentralized oracles, and communicates with other Cosmos layer-1 chains using the Inter-Blockchain Communication (IBC) protocol. Nibi-Oracle handles the voting process for validators that act as oracles by updating data feeds.
Sudo	Provides an on-chain "root" and a set of whitelisted contracts with elevated permissions. Includes management of Zero Gas Actors for fee-less CosmWasm executions against approved contracts.

Consensus Engine

Nibiru is built on Tendermint Core (CometBFT) consensus.

---

Developing in this Codebase

Install just to run project-specific commands.

cargo install just

Nibiru projects use just as the command runner instead of make. The just tool is a modern command runner that's simpler, more readable, and self-documenting.

just            # list all available commands
just build      # build the nibid binary
just localnet   # run a local network
just test-e2e   # run EVM end-to-end tests

Ref: github.com/casey/just

Docker Development Environment

For a complete local development environment with multiple services, use our Docker Compose setup that includes:

• Multiple validator nodes: Two independent Nibiru Chain nodes for testing multi-node scenarios
• Pricefeeder services: Automated price oracle data feeds
• IBC relayer: Cross-chain communication testing with Hermes relayer
• Heart Monitor: Blockchain indexing and GraphQL API for monitoring

See contrib/docker-compose/README.md for detailed setup instructions and usage examples.

How to Install Nibiru

Assuming you already have Go installed and common tools like gcc and jq, the only commands you need to run are:

just install  # to build the node software to make a Nibiru binary
just localnet # to run a local instance of Nibiru as a live network

For installation instructions from scratch, please see INSTALL.md.

Usage instructions for the nibid CLI are available at nibiru.fi/docs/dev/cli and the Nibiru Module Reference.

[Recommended minimum specs to run a full node]

• 2CPU, 4GB RAM, 100GB SSD
• Unix system: MacOS or Ubuntu 18+

License

Unless a file notes otherwise, it will fall under the BSD-2-Clause License.