# Mining Guide

Mazze uses Proof-of-Work backed by RandomX. A node validates PoW and assembles blocks; miners search nonces that satisfy the current difficulty target.

## Mining modes (node config)

Mining behavior is controlled by `run/hydra.toml`:

* `mining_author`: reward address (base32 or 40-hex). Required for mining.
* `mining_type`: `stratum`, `cpu`, or `disable`.
* `stratum_listen_address`, `stratum_port`: stratum endpoint for external miners.
* `stratum_secret`: 64-hex secret used to authorize stratum workers (required by `mazze-miner`).
* `pow_problem_window_size`: PoW manager window size.

If `mining_type` is not set, the node defaults to:

* `stratum` when `mining_author` and `stratum_secret` are set.
* `cpu` when `mining_author` is set but `stratum_secret` is not.
* `disable` otherwise.

## Stratum mining (recommended for production)

1. Set your reward address:
   * `mining_author = "<base32-or-hex>"`
2. Enable stratum:
   * `mining_type = "stratum"`
   * `stratum_listen_address = "0.0.0.0"` (or bind to a specific IP)
   * `stratum_port = 32525`
   * `stratum_secret = "<64-hex>"` (required by `mazze-miner`)
3. Start the node:

```bash
cargo build --release -p mazze
./run/start-node.sh
```

4. Start the miner (local):

```bash
cargo build --release -p mazze-miner
./run/start-miner.sh
```

### Miner configuration

`mazze-miner` reads the stratum address and secret from the node config. You can override settings on the command line:

```bash
./target/release/mazze-miner \
  --config run/hydra.toml \
  --stratum-address 127.0.0.1:32525 \
  --num-threads 16 \
  --worker-id 1
```

The helper script `run/start-miner.sh` also supports environment variables:

* `NUM_THREADS` (default: 16)
* `WORKER_ID` (default: 1)
* `RANDOMX_FULL_MEM` (default: 0, set to `1` for full-memory RandomX)

If miners are remote, expose `stratum_port` and set `stratum_listen_address` accordingly.

## CPU mining (single-node)

For a single machine without stratum workers:

1. Set `mining_author`.
2. Set `mining_type = "cpu"`.
3. Start the node (`./run/start-node.sh`).

No separate miner process is needed in CPU mode.

## Dev mode (no PoW)

In dev mode, blocks can be generated without PoW:

* `mode = "dev"`
* `dev_block_interval_ms = 500` (or omit for tx-triggered blocks)
* `mining_type = "disable"`

Use `run/start-node-dev.sh` to generate a dev config automatically.

## Monitoring mining

* Logs: `run/logs/mazze-node.log` and `run/logs/mazze-miner.log`.
* RPC checks:
  * `mazze_getStatus` (chain progress).
  * `mazze_getBlockRewardInfo` (reward data per epoch).

## Related docs

* `../architecture/pow-and-mining.md`
* `setup-guide.md`
* `viewing-logs.md`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mazze.io/testnet/mining.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.