Mezod Chain Client

Complete guide for developing with Mezod, the reference client implementation for Mezo chain.

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

1. Clone the repository

   git clone https://github.com/mezo-org/mezod.git
   cd mezod
   
2. Install Go dependencies

   go mod download
   
3. Build the client

   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:

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

1. Write Solidity Contracts

   Use standard Ethereum tooling

2. Compile

   Use Hardhat, Foundry, or solc directly

3. Deploy

   Deploy to Mezo testnet/mainnet

4. 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

1. Configure firewall and network ports

   Set up proper network security

2. Set up proper access controls

   Configure authentication and authorization

3. Deploy monitoring stack

   Set up Prometheus and Grafana

4. 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