mhinprotocol

A Rust implementation of the MY HASH IS NICE (MHIN) protocol — a system that rewards Bitcoin transactions with aesthetically pleasing transaction IDs (those starting with leading zeros).

Overview

This library provides a database-agnostic and block parser-agnostic implementation of the MHIN protocol. It focuses purely on the protocol logic, allowing you to integrate it with any Bitcoin block source and any storage backend.

For the complete protocol specification, see docs/protocol.pdf.

Key Features

• Storage Agnostic: Bring your own database by implementing the MhinStore trait
• Block Parser Agnostic: Works with any source of bitcoin::Block data
• Parallel Pre-processing: pre_process_block can be executed in parallel across multiple blocks
• Sequential Processing: process_block must be called sequentially, block after block

Installation

Add to your Cargo.toml:

[dependencies]
mhinprotocol = "0.1"
bitcoin = "0.32"

Usage

Two-Phase Block Processing

The protocol processes blocks in two phases:

1. Pre-processing (pre_process_block): Extracts all MHIN-relevant data from a Bitcoin block. This phase is parallelizable — you can pre-process multiple blocks concurrently.

2. Processing (process_block): Updates MHIN balances in the store. This phase is sequential — blocks must be processed in order, one after another.

use mhinprotocol::{MhinProtocol, MhinConfig, MhinNetwork, MhinStore, Amount, UtxoKey};

// Implement your own store
struct MyStore { /* ... */ }

impl MhinStore for MyStore {
    fn get(&mut self, key: &UtxoKey) -> Amount {
        // Fetch MHIN balance for the given UTXO key
    }

    fn pop(&mut self, key: &UtxoKey) -> Amount {
        // Remove the entry for the given UTXO key, returning the balance
    }
    
    fn set(&mut self, key: UtxoKey, value: Amount) {
        // Store MHIN balance for the given UTXO key
    }
}

fn main() {
    // Create protocol instance with mainnet parameters
    let protocol = MhinProtocol::new(MhinConfig::for_network(MhinNetwork::Mainnet));
    let mut store = MyStore::new();
    
    // Fetch blocks from your Bitcoin source
    let blocks: Vec<bitcoin::Block> = fetch_blocks();
    
    // Phase 1: Pre-process blocks (can be parallelized)
    let mhin_blocks: Vec<_> = blocks
        .par_iter()  // Using rayon for parallelism
        .map(|block| protocol.pre_process_block(block))
        .collect();
    
    // Phase 2: Process blocks sequentially
    for mhin_block in &mhin_blocks {
        protocol.process_block(mhin_block, &mut store);
    }
}

Configuration

use mhinprotocol::{MhinConfig, MhinNetwork};

// Use one of the built-in network constants.
let mainnet = MhinConfig::MAINNET;
let testnet = MhinConfig::for_network(MhinNetwork::Testnet4);

// Or describe a fully custom configuration.
let custom = MhinConfig {
    min_zero_count: 8,
    base_reward: 8_192,
    mhin_prefix: b"MHN8",
};

Protocol Summary

Mining MHIN

• Broadcast a Bitcoin transaction whose txid starts with at least 6 zeros
• The best transaction in a block (most leading zeros) earns 4096 MHIN
• Each fewer zero reduces the reward by 16x (256, 16, 1, ...)
• Coinbase transactions are not eligible

Distribution

When MHIN is earned or transferred:

• Single output: receives the entire amount
• Multiple outputs: distributed proportionally by satoshi value (excluding last output)
• Remainder goes to the first output

Custom Distribution

Include an OP_RETURN output with:

• 4-byte prefix: MHIN
• CBOR-encoded Vec<u64> specifying exact amounts per output

Types

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.