Mezod Chain Client Development Guide

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 Comet BFT 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
User Ownership: Decentralized governance and control

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:
Terminal window
```
go mod download
```
Build the client:
Terminal window
```
make build
```

Development Environment

Local Development:

# Start local development node
make dev

# Run tests
make test

# Lint code
make lint

Docker Development:

# 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:

[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, Truffle, 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, Truffle, 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

Steps:

Configure firewall and network ports
Set up proper access controls
Deploy monitoring stack
Start node with production config

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
Sync Problems: Verify blockchain synchronization
Gas Issues: Monitor gas prices and adjust accordingly

Debug Commands

# Check node status
mezod status

# View logs
mezod logs

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

Additional Resources

Mezod Repository - Main repository
Mezo Documentation - Complete documentation
Cosmos SDK Documentation - Cosmos SDK reference
EVM Documentation - EVM specification
Testnet Guide - Testnet access and usage

Support

For development support:

Join the Mezo Discord
Check the GitHub Issues
Review the FAQ