# Brisvia Miner

Official headless CPU miner for the **Brisvia (BRVA)** network. One binary mines two ways:

- **SOLO** (default): you mine for yourself. A block you find pays your address directly.
- **POOL** (`--pool`): you mine on the PPLNS pool. Your shares are credited and the reward is shared.

RandomX proof-of-work (the same engine the node uses, so hashes are identical). TLS on by default.

> The executable keeps its original `brisvia-solo-miner` name in this release for compatibility, but it
> supports **both** SOLO and PPLNS pool mining.

## Download and verify

Get the archive for your platform from the [Releases](../../releases) page, then verify it:

    # checksums
    sha256sum -c SHA256SUMS.txt        # Linux / macOS
    # (Windows) compare Get-FileHash against SHA256SUMS.txt

On Windows, the `.exe` is Authenticode-signed. Right-click → Properties → Digital Signatures should show
**Fernando Del Collado** (SSL.com), with a timestamp. Or:

    Get-AuthenticodeSignature .\brisvia-solo-miner.exe   # Status must be "Valid"

## Usage

    # SOLO (TLS, default)
    brisvia-solo-miner --url solo.brisvia.com:3334 --address brv1... [--worker NAME] [--threads N]

    # POOL (PPLNS)
    brisvia-solo-miner --pool --url POOL_HOST:PORT --address brv1... [--worker NAME] [--threads N]

Flags:

- `--config PATH`  read settings from a JSON file (see "Config file" below). Command-line flags override it.
- `--url HOST:PORT`  the pool/solo endpoint.
- `--address brv1...`  your public payout address. Your wallet/seed/private key NEVER leaves your machine;
  only this public address travels, in the login.
- `--worker NAME`  optional label for this rig.
- `--threads N`  number of threads (default: all cores).
- `--no-tls`  disable TLS. Only for local testing. For a REMOTE host you must also pass
  `--allow-insecure-pool` (below).
- `--allow-insecure-pool`  required to mine without TLS to a non-loopback host. Without encryption a
  man-in-the-middle could rewrite your payout address, so this is an explicit, conscious opt-in.
- `-h, --help`  show usage and exit.

## Config file

Instead of typing the flags every time, keep them in a JSON file and pass `--config`:

    brisvia-solo-miner --config miner.json

Any command-line flag OVERRIDES the file (precedence: defaults < config.json < flags), so you can keep a
base config and tweak one value on the fly. Example `miner.json` (only PUBLIC data — NEVER your seed or
private key):

    {
      "url": "solo.brisvia.com:3334",
      "address": "brv1youraddress",
      "worker": "rig1",
      "threads": 4,
      "pool": false,
      "tls": true
    }

Fields: `url`, `address`, `worker`, `threads`, `pool`, `tls`, `allow_insecure_pool` — all optional. Unknown
fields (or anything that looks like a secret) are rejected. The file is read defensively (regular file,
UTF-8, up to 64 KiB).

## Block durability (important, and honest)

- **SOLO recovers pending block candidates after reconnections and process restarts.** If you find a block
  and the connection drops, it is not lost: it is stored and resent until the pool confirms it. In SOLO the
  block is yours.
- **POOL prioritizes block submissions and records unconfirmed candidates for auditing, but cannot recover
  them after reconnecting**, because each pool connection is assigned a unique piece of work (the
  `extranonce1` baked into the coinbase). If the link drops in the instant between finding a block and the
  pool receiving it, that block is lost — the same as any pool miner. In POOL the block goes to the pool and
  is split by PPLNS; your credit is by shares.

A `[BLOCK] ... the pool reported it accepted (not a network confirmation)` message means the **pool**
claims it accepted the block — it is not an independent confirmation by the network. The definitive
validation of a block is always done by the pool and the node, never by the miner. During the early network
(low difficulty floor) the miner may flag **many** shares as local block candidates; that is normal.

## Forensic record (POOL only)

When you find a block in POOL mode, the miner leaves local evidence in:

- Linux: `~/.local/state/brisvia-miner/pending-pool-candidates/`
- Windows: `%LOCALAPPDATA%\Brisvia\Miner\state\pending-pool-candidates\`

It is **evidence, not a recovery mechanism**: nothing is ever resent automatically from there. It stores the
header, nonce, hash and height. The directory is hard-bounded (a hostile pool can never fill your disk). It
never stores your wallet or private key — only your public address.

## Security notes

- Your wallet never leaves the machine; only the public `brv1...` address travels, in the login.
- With TLS, a middleman cannot change your payout address.
- In POOL mode you trust the pool for share crediting and the split: the block reward is collected by the
  pool and distributed via PPLNS.
- The miner only treats a solution as a block when its target is within the network limit; it rejects
  invalid or easier-than-limit targets.

## Build from source

Needs the Rust toolchain and the RandomX static library (`librandomx.a`, v1.2.2, same as the node). See
[`BUILD-INFO.txt`](BUILD-INFO.txt) for the exact toolchain, RandomX version/commit and build commands.

    RANDOMX_LIB_DIR=/path/to/randomx/build cargo build --release --bin brisvia-solo-miner

## Tested platforms

- Linux x86-64 (non-root).
- Windows 10/11 x86-64 (non-admin), self-contained `.exe` (no extra DLLs needed).

macOS is **not** provided or claimed in this release.

## Mainnet start

**1 August 2026, 15:00 UTC** (12:00 Argentina, 23:00 China).

## License

GPLv3 — see [`LICENSE`](LICENSE). Third-party components (RandomX and Rust dependencies) are listed in
[`THIRD-PARTY-NOTICES.txt`](THIRD-PARTY-NOTICES.txt).

No warranty. Mining rewards and pool/network availability are not guaranteed.
