mx-chain-go: the reference implementation of the MultiversX protocol

What this repository is

mx-chain-go is the Go implementation for the MultiversX protocol, and the README describes it as the official implementation of the MultiversX blockchain protocol. The badges make the status plain: made by MultiverX, project MultiversX Mainnet with a link to the explorer, a Go Report Card badge and a codecov coverage report. The homepage is multiversx.com.

The Progress checklist in the README is the best single description of the scope, because it enumerates the protocol subsystems that are implemented, and it is a long list. Cryptography is there with Schnorr signatures, Belare-Neven signatures, BLS signatures and a modified BLS multi-signature. The data structures cover transaction, block, account and trie. Execution covers transaction, block, state update, synchronisation and shard fork choice. Peer to peer is libp2p. Consensus is SPoS. Sharding is a fixed number of shards with a transaction dispatcher, and MetaChain has its own data structures, block processor, interceptors and resolvers, and consensus. There is a Block K finality scheme. The virtual machine section lists the K-Framework, its Go backend, IELE Core with tests, and an IELE adapter, and a second VM section lists the EVM Core with tests and an EVM adapter. Smart contracts on a sharded architecture, governance, economics, epochs with a nodes dispatcher, network sharding with an optimised wiring protocol, fee structure, async callbacks, DEX integration and bootstrap from storage are all marked as done.

Reading that list, the shape of a modern sharded proof of stake chain comes through, with one exception that stands out, and the exception is instructive. The virtual machine section lists both the K-Framework, the framework native to the chain, and IELE, and separately the EVM, which is how a chain adds Ethereum compatibility.

The licence is GPL-3.0, and the repository is not archived with the last push on 2026-10-16. The release history is regular, with v2.1.8 on 2026-10-06, v2.1.7 on 2026-09-29 and v2.1.6 on 2026-09-25.

Building the node, and a version number that has moved on

The installation section is written for someone who wants to join the network as an observer or as a validator, and it starts with the toolchain.

The README says the installation of Go should follow the official Go installation guide, and that the minimum golang version should be 1.17.6 to run the node. That figure is worth cross-checking against the module file, which declares go 1.26. The build instructions are also in the older GOPATH style, which is a clue that they were written some time ago:

# set $GOPATH if not set and export to ~/.profile along with Go binary path
$ if [[ $GOPATH=="" ]]; then GOPATH="$HOME/go" fi
$ mkdir -p $GOPATH/src/github.com/multiversx
$ cd $GOPATH/src/github.com/multiversx
$ git clone https://github.com/multiversx/mx-chain-go
$ cd mx-chain-go && git checkout master
$ cd cmd/node && go build

The current toolchain does not need the GOPATH dance, since the module file makes the project module aware, and the Makefile in the repository root has a build-cmd target that does the same thing as the last line above, a change into cmd/node and a go build. A reader with a modern Go should use make build-cmd.

One dependency is worth calling out because it changes what the binary contains. The node depends on the Wasm Virtual Machine, which is automatically managed by the node, so the WebAssembly runtime travels with the node rather than being something you install separately.

The test command is the standard one:

$ go test ./...

and the Makefile wraps it in a matrix of targets, which the testing section below covers.

Node identity: two key pairs, one of them temporary

Step three is creating the node's identity, and it contains the most interesting sentence in the whole README for anyone thinking about the protocol's direction.

To be registered in the MultiversX Network, a node must possess two types of secret key and public key pairs. One is used to identify the node's credential used to generate transactions, which means the sender field of a transaction is its account address. The other is used in the process of block signing. And the README says plainly that this is a preliminary mechanism, and that in the next releases the first pair will be dropped when the staking mechanism is fully implemented.

So the current model has a node signing blocks with one key and sending transactions from an address derived from another, and the second of those is on its way out as staking takes over. That is a protocol in transition, and the README says so rather than leaving you to infer it from the code.

The tool that generates the identity is a separate binary in cmd/keygenerator:

$ cd $GOPATH/src/github.com/multiversx/mx-chain-go/cmd/keygenerator
$ go build
$ ./keygenerator

The result is a .pem file, and the credentials it holds are the node's identity in the network. That is the operational fact to keep in mind: this is a secret that cannot be regenerated, and a validator whose key file is lost is a validator that has to be re-registered, not one that can be rebuilt.

Joining the testnet, or running on your own network

There are two routes from a built binary to a running node, and the README presents them as alternatives.

The first is joining the MultiversX testnet, which follows the steps outlined in the MultiversX documentation for validator node scripts and configuration scripts. The README explains why the route is not self-contained: in order to join the testnet you need a specific node configuration, and that configuration is described elsewhere.

The second is copying the credentials and starting a node in a separate network, which is the path for anyone running their own network or developing against one:

$  cp validatorKey.pem ./../node/config/
$  cd ../node && ./node

The credential file has to be in the same directory as the node binary, which is the kind of arrangement that looks like a convention and is really a dependency on the config layout.

The configuration model is described next, and it is worth understanding before you change anything. The node binary has flags defined, and a user can use the --help flag for a brief description. Those flags can be used to directly alter the configuration values defined in .toml and .json files, and they can be used when launching more than one instance of the binary.

That combination, files plus flags, is the standard shape for a node configuration and it has one operational consequence worth knowing: running several nodes on one machine means the ports, the directories and the peer identity all have to be separated by flags rather than by editing files, because the files are shared. The README does not describe a preset or a profile mechanism, so a deployment that wants several local nodes has to manage that separation itself.

The dependency stack, and the chain split into mx-chain modules

The go.mod file is the clearest picture of how the project is factored, and the pattern is that the node itself is the large piece and everything with a clean interface is its own module.

The MultiversX modules in the direct requirements are the interesting ones. There is mx-chain-core-go for the core data types, mx-chain-crypto-go for the signature schemes, mx-chain-communication-go for the data exchange between components, mx-chain-storage-go for persistence, mx-chain-logger-go for logging, mx-chain-es-indexer-go for the Elasticsearch indexer, mx-chain-scenario-go for the integration testing framework, mx-chain-vm-common-go for the shared virtual machine interfaces, and then three separate virtual machine modules, mx-chain-vm-go, mx-chain-vm-v1_2-go, mx-chain-vm-v1_3-go and mx-chain-vm-v1_4-go, which is how a chain keeps multiple historical VM versions alive at once so that a smart contract written against an older version still executes under the rules it was written for.

The rest of the stack is well chosen for the job. libp2p and libp2p-pubsub carry the peer to peer layer, gogo/protobuf with a protoc generator is the wire format, prometheus client_golang for the metrics, gin and gorilla/websocket for the REST and websocket API, urfave/cli for the command line, termui for the terminal interface, gopsutil and klauspost/cpuid for the machine and CPU information the node reports, and beevik/ntp for time synchronisation, which a consensus protocol needs.

The module declares go 1.26, and the pinned versions are recent, with gin at 1.12, libp2p at 0.48 and golang.org/x/crypto at 0.54.

The repository layout follows the same decomposition at the source level, with directories for api, cmd, common, config, consensus, dataRetriever, dblookupext, debug, docker, epochStart, errors, facade, factory, fallback, genesis, health, heartbeat, keysManagement, node, ntp, outport, p2p, process, redundancy, sharding, state, statusHandler, storage, trie, txcache, update and vm, plus integrationTests, testscommon and examples.

The test matrix, the protos and the dashboards

The Makefile is where this project shows its testing discipline, and it is worth reading the target names rather than the code.

The default test target excludes several directories from the package list, filtering out integrationTests, testscommon, anything matching mock, disabled or defaults, which means the ordinary go test ./... runs the unit tests and leaves the heavier suites to their own targets. Then there is a graded set: test-v for verbose, test-serial for running with a parallelism of one, test-short for the short mode, and test-race for the race detector.

After that come the targeted targets, and their names are the specification of what the project considers risky. There is test-memp2p-v for the in-memory peer to peer tests, and a set of consensus targets that run TestConsensusBLSFullTest, once against the in-memory peer to peer harness and once against the real network, in both the verbose and quiet forms. There is test-miniblocks for the block processing tests in the multi shard architecture, in both the memp2p and the real network variants, and there is test-agario-join-reward for the staking join and reward path. There is test-wasm for the WebAssembly virtual machine integration tests.

The coverage target runs the unit tests with the short flag and a cover profile, and the repository carries a codecov.yml, a sonar-project.properties file, a .golangci.yml for linting and a SECURITY.md.

The protobuf story is handled by an install-proto.sh script and a documented manual procedure for compiling new fields in .proto files, which involves downloading the protoc compiler, installing its include directory, fetching the multiversx/protobuf repository and building the gogoslick generator plugin. The README notes that this should be updated when the required pull request is merged into the gogo protobuf master branch, which is a candid admission that the toolchain is pinned to a fork rather than upstream.

The observability side is documented too. Starting the node with the --p2p-prometheus-metrics flag exposes a metrics collection at http://localhost:8080/debug/metrics/prometheus, with the port defined by the rest api interface flag, and the README then walks through cloning the libp2p repository, adding a datasource to the dashboards configuration, and running a docker compose command that brings up the preconfigured dashboards on Grafana at http://localhost:3000/dashboards.

Editorial conclusion

Adopt mx-chain-go when you intend to run a node on the MultiversX network, as an observer or a validator, since it is the reference implementation and the documentation assumes exactly that setup, with the keygenerator, the credential file and the testnet configuration. It is the wrong tool if you want to build an application on the network, because the read and write paths are served by the separate indexer and communication modules this repository depends on, and the wrong tool if you want to understand the protocol from the code alone, because the specification and the paper behind the design live elsewhere. Before starting, check the Go version, because the README says 1.17.6 is the minimum while the module file declares go 1.26, and build the binaries with make build-cmd rather than assuming the old GOPATH flow still applies to your toolchain.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. multiversx/mx-chain-go on GitHub
3. Project website
4. README
5. Releases