Mezod Chain Client

Mezod is the reference client implementation for the Mezo chain, a Bitcoin-first blockchain designed for user ownership, reliable bridging with tBTC, BTC for gas, dual staking model, and EVM compatibility.

Overview

Mezo is a Cosmos SDK-based chain with EVM compatibility running on top of CometBFT consensus engine. The Mezod client codebase was forked from the LGPL version of Evmos and heavily modified for Mezo’s specific requirements.

Key Features

Bitcoin-first Design

Native BTC integration and gas payments

EVM Compatibility

Full Ethereum Virtual Machine support

tBTC Bridging

Reliable cross-chain Bitcoin transfers

Dual Staking Model

Rewards and validation mechanisms

Repository Structure

The Mezod repository contains:

Go Modules: Core blockchain client implementation
x/ modules: Custom Cosmos SDK modules
EVM Integration: Ethereum compatibility layer
Configuration: Chain configuration and parameters

Development Setup

Prerequisites

Go 1.21+ (check go.mod for exact version)
Git
Make
Docker (optional, for containerized development)

Installation

Clone the repository

git clone https://github.com/mezo-org/mezod.git
cd mezod

Install Go dependencies

go mod download

Build the client

make build

Development Environment

Local Development
Docker Development

# Start local development node
make dev

# Run tests
make test

# Lint code
make lint

# Build Docker image
docker build -t mezod .

# Run containerized node
docker run -p 26657:26657 -p 8545:8545 mezod

Chain Configuration

Network Parameters

Mezod supports multiple network configurations:

Mainnet: Production Mezo network
Testnet: Public testing network
Local: Development network

Configuration Files

Key configuration files:

config.toml: Node configuration
app.toml: Application-specific settings
client.toml: Client configuration

Example configuration:

config.toml

[consensus]
timeout_commit = "1s"
timeout_propose = "3s"

[p2p]
laddr = "tcp://0.0.0.0:26656"
external_address = "YOUR_EXTERNAL_IP:26656"
persistent_peers = "peer1@ip1:26656,peer2@ip2:26656"

[api]
enable = true
address = "tcp://0.0.0.0:1317"

EVM Integration

Ethereum Compatibility

Mezod provides full EVM compatibility, allowing you to:

Deploy Ethereum smart contracts
Use Ethereum tooling (Hardhat, Foundry, etc.)
Interact with contracts using Web3 libraries

Connecting via Web3

import { ethers } from 'ethers';

// Connect to Mezo network
const provider = new ethers.JsonRpcProvider('https://rpc.mezo.org');

// Get network info
const network = await provider.getNetwork();
console.log('Network:', network);

// Deploy contract
const factory = new ethers.ContractFactory(abi, bytecode, signer);
const contract = await factory.deploy();
await contract.waitForDeployment();

Gas and Fees

BTC for Gas: Pay transaction fees in Bitcoin
Dynamic Pricing: Gas prices adjust based on network conditions
EVM Gas Model: Compatible with Ethereum gas calculations

Node Types

Full Node

A complete node that stores the entire blockchain:

# Start full node
mezod start

Light Client

A lightweight client for mobile and resource-constrained environments:

# Start light client
mezod start --mode light

Archive Node

A node that stores all historical data:

# Start archive node
mezod start --mode archive

RPC Endpoints

Cosmos SDK RPC

Port: 26657
Endpoints: Standard Cosmos SDK RPC methods
WebSocket: Real-time updates

# Query node status
curl http://localhost:26657/status

EVM RPC

Port: 8545
Endpoints: Ethereum-compatible JSON-RPC
Methods: eth_getBalance, eth_sendTransaction, etc.

# Query EVM balance
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x...", "latest"],"id":1}' \
  http://localhost:8545

Development Workflow

Building Contracts

Write Solidity Contracts

Use standard Ethereum tooling

Compile

Use Hardhat, Foundry, or solc directly

Deploy

Deploy to Mezo testnet/mainnet

Interact

Use Web3 libraries or direct RPC calls

Testing

# Run unit tests
make test

# Run integration tests
make test-integration

# Run specific test package
go test ./x/evm/...

Integration Examples

Cosmos SDK Integration

package main

import (
    "context"
    "github.com/cosmos/cosmos-sdk/client"
    "github.com/cosmos/cosmos-sdk/client/tx"
)

func main() {
    // Create client context
    clientCtx := client.Context{}

    // Create transaction builder
    txBuilder := clientCtx.TxConfig.NewTxBuilder()

    // Build and send transaction
    // ... transaction logic
}

Monitoring and Debugging

Logging

# Enable debug logging
mezod start --log-level debug

# Log to file
mezod start --log-file /path/to/logfile

Metrics

Prometheus: Built-in metrics collection on port 26660
Grafana: Dashboard for monitoring
Health Checks: HTTP endpoints for health monitoring

# Check metrics
curl http://localhost:26660/metrics

Deployment

Production Deployment

Hardware Requirements:

Minimum: 8GB RAM, 100GB SSD
Recommended: 16GB RAM, 500GB NVMe SSD

Configure firewall and network ports

Set up proper network security

Set up proper access controls

Configure authentication and authorization

Deploy monitoring stack

Set up Prometheus and Grafana

Start node with production config

Launch the node with production settings

Docker Deployment

# Production Docker deployment
docker run -d \
  --name mezod \
  -p 26657:26657 \
  -p 8545:8545 \
  -v /data:/root/.mezod \
  mezod:latest start

Troubleshooting

Common Issues

Connection Issues

Check RPC endpoints and network connectivity. Verify firewall rules allow traffic on required ports (26656, 26657, 8545).

Sync Problems

Verify blockchain synchronization status using mezod status. Check peer connections and ensure you have sufficient peers.

Gas Issues

Monitor gas prices and adjust accordingly. Ensure your wallet has sufficient BTC for gas fees.

Debug Commands

# Check node status
mezod status

# View logs
mezod logs

# Reset node (caution: deletes data)
mezod unsafe-reset-all

The unsafe-reset-all command will delete all blockchain data. Use with caution and ensure you have backups.

Additional Resources

Mezod Repository

Main repository and source code

Configure Environment

Set up your development environment

Cosmos SDK Documentation

Cosmos SDK reference documentation

EVM Documentation

Ethereum Virtual Machine specification

Support

For development support:

Join the Mezo Discord
Check the GitHub Issues
Review the FAQ

Get Started

Mezo Nodes

Architecture

Features

Bridge & MUSD

Reference

​Overview

​Key Features

Bitcoin-first Design

EVM Compatibility

tBTC Bridging

Dual Staking Model

​Repository Structure

​Development Setup

​Prerequisites

​Installation

​Development Environment

​Chain Configuration

​Network Parameters

​Configuration Files

​EVM Integration

​Ethereum Compatibility

​Connecting via Web3

​Gas and Fees

​Node Types

​Full Node

​Light Client

​Archive Node

​RPC Endpoints

​Cosmos SDK RPC

​EVM RPC

​Development Workflow

​Building Contracts

​Testing

​Integration Examples

​Cosmos SDK Integration

​Monitoring and Debugging

​Logging

​Metrics

​Deployment

​Production Deployment

​Docker Deployment

​Troubleshooting

​Common Issues

​Debug Commands

​Additional Resources

Mezod Repository

Configure Environment

Cosmos SDK Documentation

EVM Documentation

​Support

Build docs developers (and LLMs) love

Overview

Key Features

Repository Structure

Development Setup

Prerequisites

Installation

Development Environment

Chain Configuration

Network Parameters

Configuration Files

EVM Integration

Ethereum Compatibility

Connecting via Web3

Gas and Fees

Node Types

Full Node

Light Client

Archive Node

RPC Endpoints

Cosmos SDK RPC

EVM RPC

Development Workflow

Building Contracts

Testing

Integration Examples

Cosmos SDK Integration

Monitoring and Debugging

Logging

Metrics

Deployment

Production Deployment

Docker Deployment

Troubleshooting

Common Issues

Debug Commands

Additional Resources

Support