zeldhash-protocol

A Rust implementation of the ZELDHASH (ZELD) 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 ZELD 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 ZeldStore 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]
zeldhash-protocol = "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 ZELD-relevant data from a Bitcoin block. This phase is parallelizable — you can pre-process multiple blocks concurrently.

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

use zeldhash_protocol::{ZeldProtocol, ZeldConfig, ZeldNetwork, ZeldStore, Balance, UtxoKey};

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

impl ZeldStore for MyStore {
    fn get(&mut self, key: &UtxoKey) -> Balance {
        // Fetch stored balance (positive = spendable, negative = spent tombstone)
    }

    fn set(&mut self, key: UtxoKey, value: Balance) {
        // Store balance for the given UTXO key
    }
}

fn main() {
    // Create protocol instance with mainnet parameters
    let protocol = ZeldProtocol::new(ZeldConfig::for_network(ZeldNetwork::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 zeld_blocks: Vec<_> = blocks
        .par_iter()  // Using rayon for parallelism
        .map(|block| protocol.pre_process_block(block))
        .collect();
    
    // Phase 2: Process blocks sequentially
    for zeld_block in &zeld_blocks {
        protocol.process_block(zeld_block, &mut store);
    }
}

Configuration

use zeldhash_protocol::{ZeldConfig, ZeldNetwork};

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

// Or describe a fully custom configuration.
let custom = ZeldConfig {
    min_zero_count: 8,
    base_reward: 8_192,
    zeld_prefix: b"ZELD",
    network: bitcoin::Network::Bitcoin,
};

Protocol Summary

Mining ZELD

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

Distribution

When ZELD is earned or transferred:

• By default, all ZELD goes to the first non-OP_RETURN output
• Newly mined rewards always attach to the first non-OP_RETURN output
• If a transaction has only OP_RETURN outputs, any ZELD is burned

Custom Distribution

Include an OP_RETURN output with:

• 4-byte prefix: ZELD
• CBOR-encoded array of u64 specifying exact amounts per non-OP_RETURN output
• Extra entries are ignored; missing entries default to 0
• If the requested sum exceeds the available ZELD, the custom plan is ignored and everything goes to the first non-OP_RETURN output
• If the requested sum is below the available ZELD, the remainder is added to the first non-OP_RETURN output
• Only the last valid OP_RETURN payload is considered
• Important: All inputs must be signed with SIGHASH_ALL (or SIGHASH_DEFAULT for Taproot) for the custom distribution to apply. This ensures the distribution cannot be altered after signing. Supported script types: P2PKH, P2WPKH, P2SH-multisig, P2WSH, and P2TR.

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.