Skip to content
Mezo Documentation

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:

Development Setup

Prerequisites

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

Installation

  1. Clone the repository:
Terminal window
git clone https://github.com/mezo-org/mezod.git
cd mezod
  1. Install Go dependencies:
Terminal window
go mod download
  1. Build the client:
Terminal window
make build

Development Environment

  1. Local Development:
Terminal window
# Start local development node
make dev


# Run tests
make test


# Lint code
make lint
  1. Docker Development:
Terminal window
# 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, 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:

Terminal window
# Start full node
mezod start

Light Client

A lightweight client for mobile and resource-constrained environments:

Terminal window
# Start light client
mezod start --mode light

Archive Node

A node that stores all historical data:

Terminal window
# Start archive node
mezod start --mode archive

RPC Endpoints

Cosmos SDK RPC

  • Port: 26657
  • Endpoints: Standard Cosmos SDK RPC methods
  • WebSocket: Real-time updates
Terminal window
# Query node status
curl http://localhost:26657/status

EVM RPC

  • Port: 8545
  • Endpoints: Ethereum-compatible JSON-RPC
  • Methods: eth_getBalance, eth_sendTransaction, etc.
Terminal window
# 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, Truffle, or solc directly
  3. Deploy: Deploy to Mezo testnet/mainnet
  4. Interact: Use Web3 libraries or direct RPC calls

Testing

Terminal window
# 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

Terminal window
# 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
Terminal window
# Check metrics
curl http://localhost:26660/metrics

Deployment

Production Deployment

Hardware Requirements:

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

Steps:

  1. Configure firewall and network ports
  2. Set up proper access controls
  3. Deploy monitoring stack
  4. Start node with production config

Docker Deployment

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

Troubleshooting

Common Issues

  1. Connection Issues: Check RPC endpoints and network connectivity
  2. Sync Problems: Verify blockchain synchronization
  3. Gas Issues: Monitor gas prices and adjust accordingly

Debug Commands

Terminal window
# Check node status
mezod status


# View logs
mezod logs


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

Additional Resources

Support

For development support: