README
¶
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
- Developing in this Codebase
- 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
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.
Directories
¶
| Path | Synopsis |
|---|---|
|
appconst
Package appconst defines global constants and utility functions used throughout the Nibiru application.
|
Package appconst defines global constants and utility functions used throughout the Nibiru application. |
|
cmd
|
|
|
nibid
command
|
|
|
contrib
|
|
|
scripts
command
|
|
|
embeds
Package "embeds" adds access to files (smart contracts) embedded in the Go runtime.
|
Package "embeds" adds access to files (smart contracts) embedded in the Go runtime. |
|
embeds/gen-abi
command
|
|
|
evmstate
Package "evm/evmstate" implements a go-ethereum vm.StateDB for Nibiru's Multi VM stack, implemented as SDB.
|
Package "evm/evmstate" implements a go-ethereum vm.StateDB for Nibiru's Multi VM stack, implemented as SDB. |
|
precompile
Package precompile implements custom precompiles for the Nibiru EVM.
|
Package precompile implements custom precompiles for the Nibiru EVM. |
|
lib
|
|
|
cosmos-sdk/baseapp
Deprecated.
|
Deprecated. |
|
cosmos-sdk/baseapp/testutil/mock
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
cosmos-sdk/client/docs/statik
Package statik contains static assets.
|
Package statik contains static assets. |
|
cosmos-sdk/client/grpc/node
Package node is a reverse proxy.
|
Package node is a reverse proxy. |
|
cosmos-sdk/client/grpc/reflection
Package reflection is a reverse proxy.
|
Package reflection is a reverse proxy. |
|
cosmos-sdk/client/grpc/tmservice
Package tmservice is a reverse proxy.
|
Package tmservice is a reverse proxy. |
|
cosmos-sdk/codec/legacy
Package legacy contains a global amino Cdc which is deprecated but still used in several places within the SDK.
|
Package legacy contains a global amino Cdc which is deprecated but still used in several places within the SDK. |
|
cosmos-sdk/codec/types
Package types defines a custom wrapper for google.protobuf.Any which supports cached values as well as InterfaceRegistry which keeps track of types which can be used with Any for both security and introspection
|
Package types defines a custom wrapper for google.protobuf.Any which supports cached values as well as InterfaceRegistry which keeps track of types which can be used with Any for both security and introspection |
|
cosmos-sdk/codec/unknownproto
unknownproto implements functionality to "type check" protobuf serialized byte sequences against an expected proto.Message to report:
|
unknownproto implements functionality to "type check" protobuf serialized byte sequences against an expected proto.Message to report: |
|
cosmos-sdk/crypto/hd
Package hd provides support for hierarchical deterministic wallets generation and derivation.
|
Package hd provides support for hierarchical deterministic wallets generation and derivation. |
|
cosmos-sdk/crypto/keyring
Package keyring provides common key management API.
|
Package keyring provides common key management API. |
|
cosmos-sdk/crypto/keys/bcrypt
Package bcrypt implements Provos and Mazières's bcrypt adaptive hashing algorithm.
|
Package bcrypt implements Provos and Mazières's bcrypt adaptive hashing algorithm. |
|
cosmos-sdk/crypto/keys/internal/ecdsa
Package ECDSA implements Cosmos-SDK compatible ECDSA public and private key.
|
Package ECDSA implements Cosmos-SDK compatible ECDSA public and private key. |
|
cosmos-sdk/crypto/keys/secp256r1
Package secp256r1 implements Cosmos-SDK compatible ECDSA public and private key.
|
Package secp256r1 implements Cosmos-SDK compatible ECDSA public and private key. |
|
cosmos-sdk/internal/conv
Package conv provides internal functions for convertions and data manipulation
|
Package conv provides internal functions for convertions and data manipulation |
|
cosmos-sdk/server
The commands from the SDK are defined with `cobra` and configured with the `viper` package.
|
The commands from the SDK are defined with `cobra` and configured with the `viper` package. |
|
cosmos-sdk/server/grpc/gogoreflection
Package gogoreflection implements gRPC reflection for gogoproto consumers the normal reflection library does not work as it points to a different singleton registry.
|
Package gogoreflection implements gRPC reflection for gogoproto consumers the normal reflection library does not work as it points to a different singleton registry. |
|
cosmos-sdk/server/grpc/reflection/v2alpha1
Package v2alpha1 is a reverse proxy.
|
Package v2alpha1 is a reverse proxy. |
|
cosmos-sdk/std
Package std defines all the common and standard inter-module Cosmos SDK types and definitions modules and applications can depend on.
|
Package std defines all the common and standard inter-module Cosmos SDK types and definitions modules and applications can depend on. |
|
cosmos-sdk/store/pruning/mock
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
cosmos-sdk/testutil/mock
Package mock is a generated GoMock package.
|
Package mock is a generated GoMock package. |
|
cosmos-sdk/testutil/network
Package network implements and exposes a fully operational in-process Tendermint test network that consists of at least one or potentially many validators.
|
Package network implements and exposes a fully operational in-process Tendermint test network that consists of at least one or potentially many validators. |
|
cosmos-sdk/types/bech32/legacybech32
Deprecated: The module provides legacy bech32 functions which will be removed in a future release.
|
Deprecated: The module provides legacy bech32 functions which will be removed in a future release. |
|
cosmos-sdk/types/errors
Package errors provides a shared set of errors for use in the SDK, aliases functionality in the cosmossdk.io/errors module that used to be in this package, and provides some helpers for converting errors to ABCI response code.
|
Package errors provides a shared set of errors for use in the SDK, aliases functionality in the cosmossdk.io/errors module that used to be in this package, and provides some helpers for converting errors to ABCI response code. |
|
cosmos-sdk/types/module
Package module contains application module patterns and associated "manager" functionality.
|
Package module contains application module patterns and associated "manager" functionality. |
|
cosmos-sdk/types/tx
Package tx is a reverse proxy.
|
Package tx is a reverse proxy. |
|
cosmos-sdk/version
Package version is a convenience utility that provides SDK consumers with a ready-to-use version command that produces apps versioning information based on flags passed at compile time.
|
Package version is a convenience utility that provides SDK consumers with a ready-to-use version command that produces apps versioning information based on flags passed at compile time. |
|
cosmos-sdk/x/auth/ante/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/auth/migrations/v2
Package v2 creates in-place store migrations for fixing tracking delegations with vesting accounts.
|
Package v2 creates in-place store migrations for fixing tracking delegations with vesting accounts. |
|
cosmos-sdk/x/auth/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/auth/types
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages.
|
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages. |
|
cosmos-sdk/x/auth/vesting/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/authz
Package authz is a reverse proxy.
|
Package authz is a reverse proxy. |
|
cosmos-sdk/x/authz/codec
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgGrant or MsgExec instance so that they can be (de)serialized properly.
|
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgGrant or MsgExec instance so that they can be (de)serialized properly. |
|
cosmos-sdk/x/authz/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/bank/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/bank/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
cosmos-sdk/x/consensus/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/consensus/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
cosmos-sdk/x/crisis/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/distribution
Package distribution implements a Cosmos SDK module, that provides an implementation of the F1 fee distribution algorithm.
|
Package distribution implements a Cosmos SDK module, that provides an implementation of the F1 fee distribution algorithm. |
|
cosmos-sdk/x/distribution/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/distribution/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
cosmos-sdk/x/evidence
Package evidence implements a Cosmos SDK module, per ADR 009, that allows for the submission and handling of arbitrary evidence of misbehavior.
|
Package evidence implements a Cosmos SDK module, per ADR 009, that allows for the submission and handling of arbitrary evidence of misbehavior. |
|
cosmos-sdk/x/evidence/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/evidence/types
DONTCOVER
|
DONTCOVER |
|
cosmos-sdk/x/feegrant
Package feegrant provides functionality for authorizing the payment of transaction fees from one account (key) to another account (key).
|
Package feegrant provides functionality for authorizing the payment of transaction fees from one account (key) to another account (key). |
|
cosmos-sdk/x/feegrant/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/genutil
Package genutil contains a variety of genesis utility functionality for usage within a blockchain application.
|
Package genutil contains a variety of genesis utility functionality for usage within a blockchain application. |
|
cosmos-sdk/x/genutil/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/gov/codec
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgSubmitProposal instance so that they can be (de)serialized properly.
|
Package codec provides a singleton instance of Amino codec that should be used to register any concrete type that can later be referenced inside a MsgSubmitProposal instance so that they can be (de)serialized properly. |
|
cosmos-sdk/x/gov/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/gov/types/v1
Package v1 is a reverse proxy.
|
Package v1 is a reverse proxy. |
|
cosmos-sdk/x/gov/types/v1beta1
Package v1beta1 is a reverse proxy.
|
Package v1beta1 is a reverse proxy. |
|
cosmos-sdk/x/params
Package params provides a namespaced module parameter store.
|
Package params provides a namespaced module parameter store. |
|
cosmos-sdk/x/params/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/params/types
To prevent namespace collision between consumer modules, we define a type Subspace.
|
To prevent namespace collision between consumer modules, we define a type Subspace. |
|
cosmos-sdk/x/params/types/proposal
Package proposal is a reverse proxy.
|
Package proposal is a reverse proxy. |
|
cosmos-sdk/x/simulation
Package simulation implements a full fledged Cosmos SDK application used for executing simulation test suites.
|
Package simulation implements a full fledged Cosmos SDK application used for executing simulation test suites. |
|
cosmos-sdk/x/slashing/migrations/v1
Package v040 is copy-pasted from: https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/x/slashing/types/keys.go
|
Package v040 is copy-pasted from: https://github.com/cosmos/cosmos-sdk/blob/v0.41.0/x/slashing/types/keys.go |
|
cosmos-sdk/x/slashing/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/slashing/types
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages.
|
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages. |
|
cosmos-sdk/x/staking/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
cosmos-sdk/x/staking/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
cosmos-sdk/x/upgrade
Package upgrade provides a Cosmos SDK module that can be used for smoothly upgrading a live Cosmos chain to a new software version.
|
Package upgrade provides a Cosmos SDK module that can be used for smoothly upgrading a live Cosmos chain to a new software version. |
|
cosmos-sdk/x/upgrade/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/modules/apps/27-interchain-accounts/controller/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/modules/apps/27-interchain-accounts/host/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/modules/apps/transfer/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/modules/core/02-client
Package client implements the ICS 02 - Client Semantics specification https://github.com/cosmos/ibc/tree/master/spec/core/ics-002-client-semantics.
|
Package client implements the ICS 02 - Client Semantics specification https://github.com/cosmos/ibc/tree/master/spec/core/ics-002-client-semantics. |
|
ibc-go/modules/core/02-client/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/modules/core/03-connection/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/modules/core/04-channel/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/modules/core/24-host
24-host is an implementation of ICS24.
|
24-host is an implementation of ICS24. |
|
ibc-go/modules/light-clients/06-solomachine
Package solomachine implements a concrete `ConsensusState`, `Header`, `Misbehaviour` and `Equivocation` types for the Solo Machine light client.
|
Package solomachine implements a concrete `ConsensusState`, `Header`, `Misbehaviour` and `Equivocation` types for the Solo Machine light client. |
|
ibc-go/modules/light-clients/07-tendermint
Package tendermint implements a concrete `ConsensusState`, `Header`, `Misbehaviour` and `Equivocation` types for the Tendermint consensus light client.
|
Package tendermint implements a concrete `ConsensusState`, `Header`, `Misbehaviour` and `Equivocation` types for the Tendermint consensus light client. |
|
ibc-go/modules/light-clients/08-wasm
Package wasm implements a concrete ClientState, ConsensusState, ClientMessage and types for the proxy light client module communicating with underlying Wasm light clients.
|
Package wasm implements a concrete ClientState, ConsensusState, ClientMessage and types for the proxy light client module communicating with underlying Wasm light clients. |
|
ibc-go/modules/light-clients/08-wasm/testing/simapp/params
Package params defines the simulation parameters in the simapp.
|
Package params defines the simulation parameters in the simapp. |
|
ibc-go/modules/light-clients/08-wasm/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
ibc-go/testing
This file contains the variables, constants, and default values used in the testing package and commonly defined in tests.
|
This file contains the variables, constants, and default values used in the testing package and commonly defined in tests. |
|
ibc-go/testing/mock
This package is only intended to be used for testing core IBC.
|
This package is only intended to be used for testing core IBC. |
|
ibc-go/testing/simapp/params
Package params defines the simulation parameters in the simapp.
|
Package params defines the simulation parameters in the simapp. |
|
wasmvm/cmd/demo
command
|
|
|
document_hash
command
/
|
/ |
|
main
command
|
|
|
x
|
|
|
bank/testutil
Package testutil is a generated GoMock package.
|
Package testutil is a generated GoMock package. |
|
devgas/v1/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
epochs
Package epochs is a reverse proxy.
|
Package epochs is a reverse proxy. |
|
mint
Package inflation implements the token inflation for the staking and utility token of the network as described by the "Community" portion of the Nibiru Chain tokenomics.
|
Package inflation implements the token inflation for the staking and utility token of the network as described by the "Community" portion of the Nibiru Chain tokenomics. |
|
nutil/localnet
Package localnet provides test helpers for connecting Go tests to an already- running Nibiru localnet.
|
Package localnet provides test helpers for connecting Go tests to an already- running Nibiru localnet. |
|
nutil/omap
Package omap defines a generic-based type for creating ordered maps.
|
Package omap defines a generic-based type for creating ordered maps. |
|
nutil/testutil
Package nullify provides methods to init nil values structs for test assertion.
|
Package nullify provides methods to init nil values structs for test assertion. |
|
oracle/keeper
nolint
|
nolint |
|
oracle/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
sudo
Package sudo provides a simple way to manage, verify, and run smart contracts with elevated permissions, mimicking the functionality of a Unix-based sudoers file.
|
Package sudo provides a simple way to manage, verify, and run smart contracts with elevated permissions, mimicking the functionality of a Unix-based sudoers file. |
|
tokenfactory/types
Package types is a reverse proxy.
|
Package types is a reverse proxy. |
|
wasm
autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/Cosmwasm/wasmd/x/wasm/types ALIASGEN: github.com/NibiruChain/nibiru/v2/x/wasm/keeper
|
autogenerated code using github.com/rigelrozanski/multitool aliases generated for the following subdirectories: ALIASGEN: github.com/Cosmwasm/wasmd/x/wasm/types ALIASGEN: github.com/NibiruChain/nibiru/v2/x/wasm/keeper |
|
wasm/types
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages.
|
NOTE: Usage of x/params to manage parameters is deprecated in favor of x/gov controlled execution of MsgUpdateParams messages. |
Click to show internal directories.
Click to hide internal directories.