Event Miner

A multithreaded command-line tool for adding NIP-13 Proof-of-Work to Nostr events using the nostr_core_lib.

Features

• Multithreaded mining - Use multiple CPU cores for faster mining
• Static linking - No external dependencies, self-contained binary
• Flexible input - Read events from stdin or files
• Timeout support - Optional mining timeout
• Standards compliant - Uses NIP-13 proof-of-work specification

Building

Prerequisites

• GCC compiler
• Make
• Git (for submodules)

Build Steps

# Clone the repository (if not already done)
git clone <repository-url>
cd event_miner

# Initialize and update the nostr_core_lib submodule (if needed)
git submodule update --init --recursive

# Build the project
make

# The static binary will be created as ./event_miner

Build Options

make                # Build event_miner
make clean          # Clean all build artifacts
make clean-miner    # Clean only event_miner binary
make test           # Build and run basic test
make help           # Show build help

Usage

Basic Syntax

./event_miner -pow <difficulty> -nsec <private_key> -threads <count> [options]

Required Arguments

• -pow <difficulty> - Number of leading zero bits for proof-of-work (e.g., 4 for difficulty 4)
• -nsec <private_key> - Private key in hex or nsec bech32 format
• -threads <count> - Number of mining threads to use

Optional Arguments

• -e <filename> - Read event from file (default: stdin)
• --timeout_min <minutes> - Mining timeout in minutes (default: no timeout)
• -h, --help - Show help message

Examples

Using stdin

echo '{"kind":1,"content":"Hello Nostr!","tags":[],"created_at":1723666800,"pubkey":"..."}' | \
  ./event_miner -pow 4 -nsec nsec1abc123... -threads 8

Using file input

./event_miner -pow 4 -nsec 1234567890abcdef... -threads 8 -e event.json

With timeout

./event_miner -pow 6 -nsec nsec1abc123... -threads 4 -e event.json --timeout_min 10

Input Format

The input event must be a valid JSON object with the standard Nostr event structure:

{
  "kind": 1,
  "content": "Hello, Nostr!",
  "tags": [],
  "created_at": 1723666800,
  "pubkey": "..."
}

Output Format

The mined event will be output to stdout with the proof-of-work nonce added:

{
  "kind": 1,
  "content": "Hello, Nostr!",
  "pubkey": "...",
  "id": "...",
  "sig": "...",
  "tags": [["nonce", "12345", "4"]],
  "created_at": 1755197090
}

The nonce tag contains:

• The nonce value that produces the required difficulty
• The target difficulty level
• Additional PoW-related data per NIP-13

Private Key Formats

The tool accepts private keys in two formats:

1. Hex format (64 characters): 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
2. Bech32 nsec format: nsec1abc123def456...

Performance Tips

• Use more threads on multi-core systems for faster mining
• Higher difficulty levels take exponentially more time
• Consider using timeout for very high difficulty levels
• The tool automatically manages thread coordination and early termination

Architecture

• Single-file implementation - All code in event_miner.c
• Static linking - Links with nostr_core_lib/libnostr_core.a
• Thread-safe - Uses pthread mutexes and condition variables
• Memory efficient - Proper cleanup and error handling
• Standards compliant - Implements NIP-13 proof-of-work specification

Dependencies

The project uses the nostr_core_lib submodule which includes:

• secp256k1 for cryptographic operations
• cJSON for JSON handling
• OpenSSL for additional crypto functions

All dependencies are statically linked into the final binary.

Exit Codes

• 0 - Success (mined event output to stdout)
• 1 - Error (invalid arguments, file not found, timeout, etc.)

License

This project uses the same license as the nostr_core_lib dependency.