159 lines
3.9 KiB
Markdown
159 lines
3.9 KiB
Markdown
# 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.
|