terra-money/mantlemint

What is Mantlemint?

Mantlemint is a fast core optimized for serving massive user queries.

Native query performance on RPC is slow and is not suitable for massive query handling, due to the inefficiencies introduced by IAVL tree. Mantlemint is running on fauxMerkleTree mode, basically removing the IAVL inefficiencies while using the same core to compute the same module outputs.

If you are looking to serve any kind of public node accepting varying degrees of end-user queries, it is recommended that you run a mantlemint instance alongside of your RPC. While mantlemint is indeed faster at resolving queries, due to the absence of IAVL tree and native tendermint, it cannot join p2p network by itself. Rather, you would have to relay finalized blocks to mantlemint, using RPC's websocket.

Currently supported terra-money/core versions

columbus-5 | terra-money/core@0.5.x | tendermint v0.34.x

Features

Superior LCD performance
- With the exception of Tendermint RPC/Transactions.
Super reliable and effective LCD response cache to prevent unnecessary computation for query resolving
Fully archival; historical states are available with ?height query parameter.
Useful default indexes

Installation

This specific directory contains mantlemint implementation for @terra-money/core@0.5.x (compatible with tendermint@0.34.x).

Go v1.17+ is recommended for this project (install instructions).

As a statically-linked application

$ make build-static # results in build/mantlemint

As a dynamically-linked application

$ make build # results in build/mantlemint
$ make install # results in $GOPATH/bin/mantlemint

Usage

Preparation

Access to at least 1 running RPC node with archival ability. Node synced with pruned snapshot DOES NOT work. Since mantlemint cannot join p2p network by itself, it depends on RPC to receive recently proposed blocks. Any archival Terra node with port 26657 enabled can be used for this.
config/app.toml

Mantlemint internally runs the same Terra Core, therefore you need to provide the same configuration files as if you would run an RPC. Bare minimum you would at least need app.toml.
A genesis file (link)

WARNING: It is required to run mantlemint in a separate $HOME directory than RPC; while mantlemint maintains its own database, some of the data may be overwritten by either mantlemint or RPC and may cause trouble.

Run Mantlemint

Mantlemint depends on 2 configs:

$HOME/config/app.toml; you can reuse app.toml you're using with core
Environment variables; mantlemint specific runtime variables to configure various properties of mantlemint. Examples as follows

WARNING: Make sure you separate MANTLEMINT_HOME from other mantlemint instances, or core. Doing so may result in an undefined behaviour.

# Location of genesis file
GENESIS_PATH=config/genesis.json \

# Home directory for mantlemint.
# Mantlemint will use this to:
# - read $HOME/config/app.toml
# - create and maintain $HOME/mantlemint.db directory
# - create and maintain $HOME/data/* for wasm blobs; (unsafe to share with RPC!)
# - create and maintain $HOME/$(INDEXER_DB).db for mantle indexers
MANTLEMINT_HOME=mantlemint \

# Chain ID
CHAIN_ID=columbus-5 \

# RPC Endpoint; used to sync previous blocks when mantlemint is catching up
RPC_ENDPOINTS=http://rpc1:26657,http://rpc2:26657 \

# WS Endpoint; used to sync live block as soon as they are available through RPC websocket
WS_ENDPOINTS=ws://rpc1:26657/websocket,ws://rpc2:26657/websocket \

# Name of mantlemint.db, akin to application.db for core
MANTLEMINT_DB=mantlemint \

# Name of indexer db
INDEXER_DB=indexer \

# Flag to enable/disable mantlemint sync, mainly for debugging
DISABLE_SYNC=false \

# Flag to enable/disable export module. Used for accounts export and circulating supply endpoint
ENABLE_EXPORT_MODULE=true \

# Length of richlist. it have to be greater than or equal to 0, richlist function will be off if length is 0
RICHLIST_LENGTH=100 \

# Threshold(the minimum amount) of richlist
# NOTE: this is *not* low limit of the richlist to be shown
#       this is about internal parameter to manage memory usage.
RICHLIST_THRESHOLD=10000000000uluna \

# Run sync binary (compiled with `make install`)
mantlemint

# Optional: crisis module's invariant check is known to take hours.
# You can skip it by providing --x-crisis-skip-assert-invariants flag
mantlemint --x-crisis-skip-assert-invariants

Adjusting smart contract memory cache size

The wasm section in app.toml may play a critical role in how mantlemint performs under heavy load. We recommend adjusting contract-memory-cache-size if you are planning to run mantlemint publicly, as loading contract instances from disk is an expensive operation.

[wasm]
# The WASM VM memory cache size in MiB not bytes.
# Adjust this if you need to hold more smart contract instances in memory (less overhead for loading contracts to memory)
contract-memory-cache-size = "16384" # 16GB

Health check

mantlemint implements /health endpoint. It is useful if you want to suppress traffics being routed to mantlemint nodes still syncing or unavailable due to whatever reason.

The endpoint will respond:

200 OK if mantlemint sync status is up-to date (i.e. syncing using websocket from RPC)
400 NOK if mantlemint is still syncing past blocks, and is not ready to serve the latest state yet.

Please note that mantlemint is still able to serve queries while /health returns NOK.

Default Indexes

/index/tx/by_height/{height}: List all transactions and their responses in a block. Equivalent to tendermint/block?height=xxx, with tx responses base64-decoded for better usability.
/index/tx/by_hash/{txHash}: Get transaction and its response by hash. Equivalent to lcd/txs/{hash}, but without hitting RPC.
/index/richlist/{height}: Get a richlist at the given height. Height supports latest.

Notable Differences from core

Uses a forked tendermint/tm-db: Disables unncessary mutexes in prefixdb methods
Replaces ABCIClient with NewConcurrentQueryClient: Removal of mutexes allow better concurrency, even during block injection
Uses single batch-protected db: All state changes are flushed at once, making it safe to read from db during block injection
Automatic failover: In case of block injection failure, mantlemint reverts back to the previous known state and retry
Strictly no tendermint; some parameters in app.toml would not affect mantlemint
Following endpoints are not implemented
- GET /blocks/
- GET /blocks/latest
- GET /txs/{hash}
- GET /txs
- GET /validatorset
- All POST variants

FAQ

Q1. Can I use public RPC (http://public-node.terra.dev:26657) as RPC and WS endpoints?

While you can, we do NOT recommend doing so. We only expose public node as a seed node for p2p, and its http/ws connection may not be stable. It is safer to have your own RPC

Q2. Can I convert existing core's database to mantlemint?

No. Mantlemint's db structure is NOT compatible with core's.

Q3. Mantlemint doesn't support tendermint queries like /blocks, /txs, but I still need them. What should I do?

You can route those traffic to an existing RPC that you use for RPC_ENDPOINTS and WS_ENDPOINTS with a load balancer.

Q4. Is it possible to disable archive? It takes up too much space!

Not yet, although it is on the roadmap.

Q5. Mantlemint seems to hang up on the first block.

Processing genesis block is known to take 2+ hours -- be patient!

Also, try disabling crisis module's invariant check on genesis block creation, by providing flag --x-crisis-skip-assert-invariants.

Q6. What are the system requirements to run mantlemint safely?

4 or more CPU cores
At least 16GB memory, 32~64GB for genesis block creation.
- You can scale down to smaller system after mantlemint successfully creates the genesis block
At least 2TB disk space, although we recommend bigger.

Q7. Are snapshots provided?

Not yet, but we have plans to do so.

Q8. What directories should I backup when creating snapshot?

${MANTLEMINT_HOME}/data
${MANTLEMINT_HOME}/indexer.db
${MANTLEMINT_HOME}/mantlemint.db

Community

License

This software is licensed under the Apache 2.0 license. Read more about it here.

terra-money / mantlemint