nvnmchain

README

NVNMChain

NVNMChain is a blockchain platform for anchoring document hashes and off-chain artifacts on-chain, built as an ICS (Interchain Security) consumer chain. It uses the MANTRA EVM fork to expose EVM-compatible execution on top of Cosmos SDK, with custom modules for on-chain document anchoring and fee taxation.

Table of Contents

• Overview
• Architecture
• Modules
• Getting Started
• Development
• Security

Overview

NVNMChain is an ICS opt-in consumer chain secured by a provider chain (e.g. MANTRAChain) via Interchain Security v7. It runs an EVM execution environment using a MANTRA fork of cosmos/evm, enabling Solidity smart contracts and EVM precompiles alongside native Cosmos SDK transactions.

As an ICS consumer chain, NVNMChain has no native staking at launch — validator security is inherited entirely from the provider chain.

The gas token differs by environment:

• ICS deployment: the IBC-wrapped MantraUSD token (transfer/channel-1/erc20:<wMantraUSD address>), bridged from the provider chain.
• Standalone local devnet (make build-and-run-single-node): anvnm, a placeholder denom used for development without a live provider chain.

Architecture

NVNMChain is built on:

• Cosmos SDK (MANTRA-Chain/cosmos-sdk v0.53.6)
• MANTRA EVM (MANTRA-Chain/evm v0.6.0-v8-mantra-1) — EVM execution with ERC-20 module and feemarket
• IBC Go v10 — cross-chain communication
• Interchain Security v7 — validator set security from the provider chain
• IBC Rate Limiting — token transfer rate limits

Modules

x/anchoring

Manages registries and versioned records for anchoring off-chain artifacts (e.g. documents, certificates) on-chain. Each record contains a checksum, URI, optional metadata, and a status field. Records are versioned per checksum within a registry.

Key features:

• RBAC (role-based access control) scoped per registry or per checksum
• Roles: admin, editor
• EVM precompile at 0x0000000000000000000000000000000000000a00

See x/anchoring/README.md for full ABI, function selectors, and usage details.

x/tax

Collects a configurable percentage of block fees and forwards them to a designated address. Runs in EndBlock before the CCV consumer module to ensure the tax cut is taken before any ICS reward distribution.

Parameters (governable):

• tax.Tax — fraction of fee collector balance to redirect (max 40%)
• tax.TaxAddress — destination address for collected tax

Getting Started

Prerequisites

• Go 1.24 or later

Installation

git clone https://github.com/NVNM-Chain/nvnmchain.git
cd nvnmchain
make install

Run a standalone single-node testnet

make build-and-run-single-node

This initialises a standalone node with chain ID test-chain and gas denom anvnm. This is a development-only setup with no provider chain — the gas denom differs from the ICS deployment which uses IBC-wrapped MantraUSD.

Development

Build

make build

Testing

Unit tests

make test-unit

E2E (interchain) tests

Build the Docker image and run:

make test-e2e

If the image is already built:

cd tests/interchain && go test -v -timeout 30m

Linting

Uses golangci-lint v2.12.1. Run the same version as CI to avoid false positives.

Check

docker run -t --rm -v $(pwd):/app -w /app golangci/golangci-lint:v2.12.1 golangci-lint run

Fix

docker run -t --rm -v $(pwd):/app -w /app golangci/golangci-lint:v2.12.1 golangci-lint run --fix

Generate protobuf

make proto-gen

Generate docs

make docs

Security

We take security seriously. If you discover a vulnerability, please follow the responsible disclosure process described in SECURITY.md.

---

For module-level documentation, refer to the README files under the x/ directory and architecture decisions under adr/.