# 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

```bash
# 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

```bash
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

```bash
./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
```bash
echo '{"kind":1,"content":"Hello Nostr!","tags":[],"created_at":1723666800,"pubkey":"..."}' | \
  ./event_miner -pow 4 -nsec nsec1abc123... -threads 8
```

#### Using file input
```bash
./event_miner -pow 4 -nsec 1234567890abcdef... -threads 8 -e event.json
```

#### With timeout
```bash
./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:

```json
{
  "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:

```json
{
  "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.