DOCSEARCHbyAlgolia
Submit Docs

monero-pool Documentation

repository·master·Indexed 19 days ago

https://github.com/jtgrassie/monero-pool

A high-performance Monero mining pool server written in C, optimized with libevent and LMDB. It supports RandomX (fast/full-memory mode) and features an interconnected pool architecture for high availability. Key features include block notification for reduced latency, Stratum mode self-select (SSS) to prevent centralization, and a JSON stats endpoint for custom web interfaces.

Tokens
2.4K
Snippets
6
Records
10
Agent score
14%

What's inside monero-pool

  1. Implement Stratum mode self-select (SSS)

    master

    The monero-pool supports an optional 'self-select' mode. This allows miners to bypass pool-provided block templates and instead mine on their own block templates (e.g., by fetching them from a local or remote Monero daemon). This prevents pool centralization and censorship by giving miners visibility into the transactions included in the block they are mining.

    To use this mode, the miner must follow a specific JSON-RPC handshake sequence involving the login, block_template, and job methods.

  2. Set up interconnected (upstream/downstream) pools

    master

    You can run multiple pool instances that behave as a single unit to provide low latency, redundancy, or to span network providers. Pools can be configured as edge pools, upstream pools, bridged pools, or normal single pools.

    Upstream Pool Configuration

    An upstream pool receives validated shares and blocks from downstream pools and handles payout processing. To allow downstream pools to connect, configure these parameters in the upstream pool's config:

    • trusted-listen: The IP address to bind to.
    • trusted-port: The port to listen on.
    • trusted-allowed: A comma-separated list of IP addresses allowed to connect (highly recommended for security).

    Downstream Pool Configuration

    Downstream pools relay work to the upstream. Configure these in the downstream pool's config:

    • upstream-host: The IP of the upstream pool.
    • upstream-port: The port of the upstream pool.

    Bridged Pool Configuration

    A bridged pool acts as both an edge and an upstream pool. It requires all five parameters:

    • trusted-listen, trusted-port, trusted-allowed, upstream-host, and upstream-port.
    # Upstream config example
trusted-listen = 10.0.0.1
trusted-port = 4244
trusted-allowed = 10.0.0.2,10.0.0.3

# Downstream config example
upstream-host = 10.0.0.1
upstream-port = 4244

  3. Use block notification to reduce latency

    master

    Instead of polling for new blocks using a timer, you can configure the pool to fetch a new block template immediately upon receiving a SIGUSR1 signal. This gives miners a head-start over pools using polling.

    1. Enable in Pool: Set the flag --block-notified or set block-notified = 1 in the config file.
    2. Configure Monero Daemon: Instruct monerod to send the signal using the --block-notify flag.

    Example monerod command:

    monerod ... --block-notify '/usr/bin/pkill -USR1 monero-pool'
    monerod ... --block-notify '/usr/bin/pkill -USR1 monero-pool'

  4. Install and compile monero-pool from source

    master

    To build monero-pool, you must first have the Monero source tree cloned and compiled on your system.

    1. Set Monero Root: Export the MONERO_ROOT environment variable pointing to your cloned Monero directory.
    2. Install Dependencies: You need liblmdb, libevent, json-c, and uuid. On Ubuntu, use:
      sudo apt-get install liblmdb-dev libevent-dev libjson-c-dev uuid-dev
    3. Compile:
      • For a release build (recommended): make release. Output is in build/release/.
      • For a debug build: make. Output is in build/debug/.
    export MONERO_ROOT=/path/to/cloned/monero
make release

  5. Use the Web UI and JSON stats endpoint

    master

    The pool serves a minimal web UI on the port specified in the config file.

    Best Practices:

    • Proxying: It is highly recommended to use Nginx or Apache as a reverse proxy in front of the web UI to handle browser traffic and caching.
    • Custom UIs: The HTML for the minimal UI is compiled into the binary. If you want to build your own custom web interface, do not try to modify the internal HTML; instead, consume the pool's JSON endpoint to fetch stats and balances. This allows you to keep your website completely separate from the pool process.

  6. JSON-RPC handshake for Stratum mode self-select

    master

    To implement the self-select mode, follow this sequence of JSON-RPC calls:

    1. Login: The miner initiates a login with the mode parameter set to self-select.
    2. Receive Job Data: The pool responds with a job object containing a pool_wallet and an extra_nonce.
    3. Fetch Template: The miner calls a Monero daemon's get_block_template RPC method using the extra_nonce and pool_wallet provided by the pool.
    4. Submit Template: The miner sends the fetched block template to the pool using the block_template method.
    5. Validation: The pool validates that the template is a valid Monero block and that the coinbase reward is directed to the pool_wallet.
    6. Mining & Submission: The miner performs work and submits results via the standard submit method.
    7. New Job: The pool triggers a new job via the job method, and the miner repeats from step 3.

  8. Configure monero-pool

    master

    Configuration is primarily handled via a pool.conf file.

    • Location: During compilation, a copy of pool.conf is placed in the output build directory.
    • Loading: When running the pool, it looks for the config file in the following order:
      1. The location specified via the --config-file <file> command-line parameter.
      2. The same directory as the pool binary.
      3. The current user's home directory.
    • Overrides: Many configuration options can be overridden using command-line parameters.
    ./monero-pool --config-file /path/to/custom_pool.conf

  9. Reference: Command-line parameters

    master

    The following command-line parameters can be used to override settings in the configuration file:

    -c, --config-file <file>    Specify custom configuration file
-l, --log-file <file>       Specify log file
-b, --block-notified [0|1]  Enable/disable block notification via SIGUSR1
-d, --data-dir <dir>        Specify data directory
-p, --pid-file <file>       Specify PID file
-f, --forked [0|1]          Run in forked mode

  10. Reference: Stratum mode self-select JSON-RPC messages

    master

    The following JSON-RPC message structures are required for the self-select mode implementation.

    // 1. Miner login request
{
    "method": "login",
    "params": {
        "login": "wallet address",
        "pass": "password",
        "agent": "user-agent/0.1",
        "mode": "self-select"
    },
    "jsonrpc": "2.0",
    "id": 1
}

// 2. Pool response to login (includes new fields)
{
    "result": {
        "job": {
            "pool_wallet": "pool wallet address",
            "extra_nonce": "extra nonce hex",
            "target": "target hex",
            "job_id": "job id"
        },
        "id": "client id",
        "status": "OK"
    },
    "jsonrpc": "2.0",
    "id": 1
}

// 3. Miner submits the block template
{
    "method": "block_template",
    "params": {
        "id": "client id",
        "job_id": "job id",
        "blob": "block template hex",
        "height": N,
        "difficulty": N,
        "prev_hash": "prev hash hex"
    },
    "jsonrpc": "2.0",
    "id": 1
}

// 4. Pool response to block_template
{
    "result": {
        "status": "OK",
        "error": null
    },
    "jsonrpc": "2.0",
    "id": 1
}

// 5. Standard submit (no changes)
{
    "method": "submit",
    "params": {
        "id": "client id",
        "job_id": "job id",
        "nonce": "deadbeef",
        "result": "hash hex"
    },
    "jsonrpc": "2.0",
    "id": 1
}

// 6. Pool requests new job (includes new fields)
{
    "method": "job",
    "params": {
        "pool_wallet": "pool wallet address",
        "extra_nonce": "extra nonce hex",
        "target": "target hex",
        "job_id": "job id"
    },
    "jsonrpc": "2.0",
    "id": 1
}