config.example.json

{
  // Copy this file to config.json and replace every active placeholder value.
  // Miningcore accepts comments, although strict JSON tools may not.
  // Smaller direct, multi-coin, merged-mining and relay starting points are indexed in
  // examples/README.md. This maintained reference keeps LTC/DOGE sections because they
  // demonstrate coin-specific merged-mining settings that do not apply to ordinary pools.

  // Friendly name included in logs, metrics, notifications and relayed shares.
  "clusterName": "miningcore-local",

  // Optional numeric identity for this Miningcore process in a multi-node cluster.
  // Give each node a different value; omit it for a simple single-node deployment.
  "instanceId": 1,

  // Application and API request logging.
  "logging": {
    // Minimum level: trace, debug, info, warn, error, fatal or off.
    "level": "info",
    // Write log events to stdout/stderr. Keep this enabled under systemd or Docker.
    "enableConsoleLog": true,
    // Use coloured console output when the terminal supports it.
    "enableConsoleColors": true,
    // Main log filename. Set to null to use console output only. File logs rotate natively before
    // a write would grow them beyond 512 MiB and retain four archives; do not also manage them with
    // logrotate copytruncate.
    "logFile": "miningcore.log",
    // Separate API-request log. Set to null to use the main log destination.
    "apiLogFile": "miningcore-api.log",
    // Directory for relative log filenames. Absolute paths may also be used.
    "logBaseDirectory": "logs",
    // Also create <pool-id>.log for every configured pool.
    "perPoolLogFile": false
  },

  // Public API, metrics, WebSocket notification and administrative API settings.
  "api": {
    // Set false to run Miningcore without its HTTP API.
    "enabled": true,
    // Safe copy-first baseline: a same-host reverse proxy is the only API client.
    // Container or remote exposure requires an explicit address change plus firewall,
    // whitelist, TLS and reverse-proxy review.
    "listenAddress": "127.0.0.1",
    // Main public API and WebSocket port.
    "port": 4000,
    // Dedicated administrative API port. When omitted, /api/admin remains on
    // the public port for backwards compatibility. Every admin request also requires
    // MININGCORE_ADMIN_API_TOKEN; keep it outside this file and source control.
    // Restrict this listener with the token, whitelist and a firewall.
    "adminPort": 4001,
    // Dedicated Prometheus metrics port. When omitted, /metrics remains on
    // the public port for backwards compatibility.
    "metricsPort": 4002,
    // Clients allowed to use administrative API endpoints. In Docker, host traffic does not
    // appear as container loopback; use and verify a fixed bridge gateway before publishing this
    // port to the host.
    "adminIpWhitelist": [ "127.0.0.1" ],
    // Clients allowed to scrape Prometheus metrics. A containerised Prometheus service should use
    // a dedicated network and a predictable, explicitly whitelisted address.
    "metricsIpWhitelist": [ "127.0.0.1" ],
    // Restore the older API's null-property serialization when required by a legacy UI.
    "legacyNullValueHandling": false,
    // Uncomment after placing the certificate where Miningcore can read it:
    // "tls": {
    //   "enabled": true,
    //   "tlsPfxFile": "/etc/miningcore/api-certificate.pfx",
    //   "tlsPfxPassword": "REPLACE_WITH_API_CERTIFICATE_PASSWORD"
    // },
    // Per-client API request limiting. Miningcore does not process trusted forwarded-client
    // headers. If a same-host reverse proxy connects over loopback, enforce public-client limits
    // at that proxy because Miningcore sees the proxy's loopback address, not the remote client.
    "rateLimiting": {
      // Disabling this exposes the API without application-level throttling.
      "disabled": false,
      // Addresses in this list bypass all rate-limit rules.
      "ipWhitelist": [ "127.0.0.1" ],
      // Rules are evaluated per source IP. Keep limits suitable for the chosen frontend.
      "rules": [
        {
          // Wildcard applies to every API endpoint.
          "endpoint": "*",
          // Counting window understood by AspNetCoreRateLimit.
          "period": "1s",
          // Maximum requests from one IP during the window.
          "limit": 20
        }
      ]
    }
  },

  // Connection-level abuse protection shared by all pools.
  "banning": {
    // Integrated uses Miningcore's in-process ban manager.
    "manager": "Integrated",
    // Ban clients sending data that cannot be parsed as Stratum requests.
    "banOnJunkReceive": true,
    // Allow pool-level invalid-share thresholds to ban abusive clients.
    "banOnInvalidShares": true,
    // Allow repeated invalid login attempts to trigger a ban.
    "banOnLoginFailure": true
  },

  // PostgreSQL stores shares, blocks, balances, payments and operational ownership.
  "persistence": {
    "postgres": {
      // Database endpoint as seen from Miningcore (not necessarily the daemon host).
      "host": "127.0.0.1",
      "port": 5432,
      "user": "miningcore",
      "password": "CHANGE_ME_POSTGRES_PASSWORD",
      "database": "miningcore",
      // Maximum duration in seconds for database commands.
      "commandTimeout": 60,
      // Legacy false uses opportunistic Prefer: TLS may be used, without server authentication.
      "tls": false,
      // false does NOT validate server identity in Npgsql 9, even with tls=true.
      // For remote authenticated TLS, REMOVE both legacy flags and use:
      // "sslMode": "VerifyFull",
      // "tlsRootCert": "/etc/miningcore/postgres-root-ca.crt"
      // See docs/postgres-tls.md for trust sources and migration.
      "tlsNoValidate": false
    }
  },

  // This cluster-wide switch must be enabled on the single node that owns payouts.
  "paymentProcessing": {
    // Starts block reconciliation and payout processing on this node.
    "enabled": true,
    // Seconds between payment-processing cycles.
    "interval": 600,
    // Maximum rows examined or removed from each accounting table per cycle.
    // The 50000 default keeps ahead of the documented 20-envelope/s merged-PPS baseline.
    "shareAccountingPruneBatchSize": 50000,
    // Keep exactly-once share-accounting receipts for this many days. Delayed relay
    // or recovery evidence older than this horizon is rejected for manual reconciliation.
    "shareAccountingRetentionDays": 30,
    // Optional text included in supported coinbase transactions.
    "coinbaseString": "Miningcore"
  },

  // Periodic pool, miner and network statistic aggregation.
  "statistics": {
    // Seconds between statistics updates.
    "updateInterval": 60,
    // Minutes of recent shares used to calculate displayed hashrate.
    "hashrateCalculationWindow": 5,
    // Hours between statistics cleanup/maintenance cycles.
    "gcInterval": 24,
    // Retain detailed statistics for this many days.
    "cleanupDays": 30
  },

  // Email, administrative and Pushover event delivery.
  "notifications": {
    // Master notification switch. Individual channels also have their own settings.
    "enabled": false,
    "email": {
      // SMTP server used for email notifications.
      "host": "smtp.example.com",
      "port": 587,
      "user": "CHANGE_ME_SMTP_USER",
      "password": "CHANGE_ME_SMTP_PASSWORD",
      "fromAddress": "pool@example.com",
      "fromName": "Miningcore operator"
    },
    "admin": {
      // Operational alerts for block, payment and persistence events.
      "enabled": false,
      "emailAddress": "operator@example.com",
      "notifyBlockFound": true,
      "notifyPaymentSuccess": true
    },
    "pushover": {
      // Optional Pushover destination for supported notifications.
      "enabled": false,
      "user": "CHANGE_ME_PUSHOVER_USER",
      "token": "CHANGE_ME_PUSHOVER_TOKEN"
    }
  },

  // NiceHash compatibility and automatic difficulty negotiation.
  "nicehash": {
    "enableAutoDiff": true
  },

  // Write-through emergency journal for shares or block candidates that cannot reach PostgreSQL.
  // In production use an absolute path on separately monitored/reserved storage when possible,
  // and protect it as financial accounting data.
  // Recover it with: ./Miningcore -c config.json -rs recovered-shares.txt
  "shareRecoveryFile": "recovered-shares.txt",
  // Optional outside systemd. Keep this on independent service-owned storage from the journal.
  // The supplied systemd unit automatically uses /var/lib/miningcore through StateDirectory.
  // "shareRecoveryStateDirectory": "/var/lib/miningcore",

  // Advanced relay sender example (leave commented for a direct node):
  // 192.0.2.20 is a documentation-only address; replace it with the real relay host.
  // "shareRelay": {
  //   "publishUrl": "tcp://192.0.2.20:5555",
  //   // false binds/listens; true connects to an already-bound relay endpoint.
  //   "connect": false,
  //   // Replace with a long random ZeroMQ shared secret.
  //   "sharedEncryptionKey": "REPLACE_WITH_A_LONG_RANDOM_SECRET"
  // },
  // Advanced central receiver/recorder example:
  // "shareRelays": [
  //   {
  //     "url": "tcp://192.0.2.20:5555",
  //     "sharedEncryptionKey": "REPLACE_WITH_A_LONG_RANDOM_SECRET"
  //   }
  // ],

  // Each entry defines one pool. The first two demonstrate LTC/DOGE merged mining.
  // The final disabled Bitcoin entry demonstrates an ordinary, non-merged pool and can
  // be enabled after its placeholders, difficulty and listener choices are reviewed.
  "pools": [
    {
      // Stable database/API identifier. Do not change after a production pool starts.
      "id": "ltc-solo",
      // Disabled pools remain in the file but are not started.
      "enabled": true,
      // Key from src/Miningcore/coins.json.
      "coin": "litecoin",
      // Pool-controlled Litecoin wallet address receiving parent-chain rewards.
      "address": "CHANGE_ME_LTC_POOL_WALLET_ADDRESS",
      // Expose this pool's configured Stratum ports to miners.
      "enableInternalStratum": true,
      // Milliseconds between getblocktemplate polls. ZMQ notifications can supplement polling.
      "blockRefreshInterval": 1000,
      // Re-send the current job after this many seconds without a new template; 0 disables it.
      "jobRebroadcastTimeout": 10,
      // Disconnect workers silent for this many seconds, limiting zombie socket usage.
      "clientConnectionTimeout": 600,
      // Seconds between checks for idle VarDiff connections.
      "vardiffIdleSweepInterval": 30,
      // Optional fixed reward splits (for example pool fees). Percentages reduce miner reward.
      // The zero-percent placeholder is inactive; replace or remove it before production.
      "rewardRecipients": [
        {
          "address": "CHANGE_ME_LTC_OPTIONAL_REWARD_RECIPIENT_ADDRESS",
          "percentage": 0
        }
      ],
      // One pool may expose several ports with different initial/variable difficulties.
      // Different pools may reuse a port only on distinct, non-overlapping specific addresses.
      // Miningcore reserves every enabled internal listener before any pool starts. One bind
      // failure aborts startup and releases the complete reservation set; it never starts a
      // partial cluster. Broadcast and multicast addresses are not valid listeners.
      "ports": {
        // JSON property name is the TCP port miners connect to.
        "3032": {
          // Human-readable port label shown through the API.
          "name": "LTC-DOGE-LOW-DIFF",
          // "*" listens on every IPv4 interface. A specific address must exist and be
          // bindable inside the host/container network namespace at startup.
          "listenAddress": "*",
          // Initial fixed difficulty assigned when a miner connects.
          "difficulty": 1024,
          // Optional automatic per-miner difficulty adjustment.
          "varDiff": {
            // Never retarget below this difficulty.
            "minDiff": 512,
            // Maximum difficulty; null means no configured ceiling.
            "maxDiff": null,
            // Maximum single retarget change; null uses the implementation default.
            "maxDelta": null,
            // Aim for one accepted share per miner in this many seconds.
            "targetTime": 15,
            // Recalculate difficulty at this interval in seconds.
            "retargetTime": 90,
            // Do not retarget while observed share time is within this percentage of target.
            "variancePercent": 30
          },
          // Enable TLS for this Stratum port. Supply tlsPfxFile/tlsPfxPassword when true.
          "tls": false,
          // Accept both TLS and plaintext miners by detecting the initial TLS handshake.
          "tlsAuto": false,
          // When TLS is enabled, uncomment and replace both values:
          // "tlsPfxFile": "/etc/miningcore/stratum-certificate.pfx",
          // "tlsPfxPassword": "REPLACE_WITH_STRATUM_CERTIFICATE_PASSWORD",
          // Accept HAProxy PROXY protocol information from explicitly trusted proxies only.
          "tcpProxyProtocol": {
            // Parse PROXY headers on this port.
            "enable": false,
            // Reject connections that do not supply a valid PROXY header.
            "mandatory": false,
            // Only these direct peers may assert a miner's original address.
            "proxyAddresses": [ "127.0.0.1" ]
          }
        },
        "3033": {
          // Higher starting floor for large Scrypt ASICs, farms, proxies and rentals.
          "name": "LTC-DOGE-HIGH-DIFF",
          "listenAddress": "*",
          "difficulty": 65536,
          "varDiff": {
            "minDiff": 32768,
            "maxDiff": null,
            "maxDelta": null,
            "targetTime": 15,
            "retargetTime": 90,
            "variancePercent": 30
          }
        }
      },
      // Litecoin Core JSON-RPC endpoints. Keep RPC private and wallet-enabled for payouts.
      "daemons": [
        {
          "host": "127.0.0.1",
          "port": 9332,
          "user": "CHANGE_ME_LITECOIN_RPC_USER",
          "password": "CHANGE_ME_LITECOIN_RPC_PASSWORD",
          // Optional: must exactly match litecoin.conf's zmqpubhashblock endpoint.
          // "zmqBlockNotifySocket": "tcp://127.0.0.1:29332",
          // Use HTTPS for RPC when the daemon or trusted proxy provides it.
          "ssl": false,
          // Enable only when the endpoint is known to support HTTP/2 correctly.
          "http2": false
        }
      ],
      // Pool-specific invalid-share ban threshold.
      "banning": {
        "enabled": true,
        // Evaluate the ratio after this many submitted shares.
        "checkThreshold": 50,
        // Ban when invalid shares meet or exceed this percentage.
        "invalidPercent": 50,
        // Ban duration in seconds.
        "time": 600
      },
      // Parent-chain block reconciliation and miner payouts.
      // This object is required even when the pool is disabled; set enabled=false
      // instead of removing it or replacing it with null.
      "paymentProcessing": {
        // Must be true for this example's merged-mining parent pool.
        // When this pool pays transaction fees, fund this exact wallet with a confirmed
        // reserve; minersPayTxFees covers normal sendmany fees but per-recipient fallback
        // submissions can still require additional spendable input.
        // See docs/operations.md#fee-reserve-and-balance-readiness.
        "enabled": true,
        // Smallest LTC balance paid automatically, denominated in whole LTC.
        "minimumPayment": 0.01,
        // This baseline uses SOLO; each chain may independently use SOLO, PPS, PROP or PPLNS.
        // Read docs/pps.md before enabling PPS: it requires reserve, migration and ledger checks.
        "payoutScheme": "SOLO"
        // For PPS, optionally retain statistical share rows independently of block luck:
        // "ppsShareRetentionDays": 7
      },
      // Link this Litecoin parent pool to the Dogecoin auxiliary pool below.
      "mergedMining": {
        // Set false to operate this as an ordinary Litecoin pool.
        "enabled": true,
        // Must exactly match the auxiliary pool's stable id.
        "auxPoolId": "doge-solo",
        // Password key used by miners: d=<difficulty>;doge=<DOGE address>
        "addressParameter": "doge",
        // Require and daemon-validate a DOGE beneficiary during authorisation.
        // Setting false permits parent-only mining without a DOGE address; auxiliary
        // submission is skipped for workers that do not supply one.
        "requireAuxAddress": true,
        // Milliseconds allowed for recurring createauxblock polling after startup.
        // Investigate repeated timeout/fallback metrics before raising this: a longer
        // deadline can delay a fresh parent Litecoin job.
        "auxiliaryTemplatePollTimeoutMs": 500
      }
    },
    {
      // Auxiliary pool identity referenced by ltc-solo.mergedMining.auxPoolId.
      "id": "doge-solo",
      "enabled": true,
      "coin": "dogecoin",
      // Pool-controlled Dogecoin wallet address receiving auxiliary rewards before payout.
      "address": "CHANGE_ME_DOGE_POOL_WALLET_ADDRESS",
      // Merged miners connect to the LTC port. Set true only if a separate DOGE Stratum is wanted.
      "enableInternalStratum": false,
      // Normal Dogecoin template polling interval for this pool in milliseconds.
      "blockRefreshInterval": 1000,
      // Normal Dogecoin job rebroadcast interval in seconds; 0 disables it.
      "jobRebroadcastTimeout": 10,
      // Disconnect silent direct-DOGE workers after this many seconds.
      "clientConnectionTimeout": 600,
      // Optional DOGE fee/donation recipients, using the same format as the LTC pool.
      "rewardRecipients": [
        {
          "address": "CHANGE_ME_DOGE_OPTIONAL_REWARD_RECIPIENT_ADDRESS",
          "percentage": 0
        }
      ],
      // A ports object is part of the pool contract even when internal Stratum is disabled.
      // Keep one dormant direct-mining endpoint: merged miners use the LTC ports above.
      "ports": {
        "3042": {
          // This port is not opened while enableInternalStratum is false.
          "name": "DOGE-DIRECT-DISABLED",
          "listenAddress": "127.0.0.1",
          "difficulty": 1024
        }
      },
      // Dogecoin Core RPC used for createauxblock, submitauxblock, proof attribution,
      // address validation, maturity checks and wallet payments. Configure one authoritative
      // auxiliary endpoint: merged mining warns and uses the first when several are supplied.
      "daemons": [
        {
          "host": "127.0.0.1",
          "port": 22555,
          "user": "CHANGE_ME_DOGECOIN_RPC_USER",
          "password": "CHANGE_ME_DOGECOIN_RPC_PASSWORD",
          // Optional: must exactly match dogecoin.conf's zmqpubhashblock endpoint.
          // "zmqBlockNotifySocket": "tcp://127.0.0.1:44556",
          "ssl": false,
          "http2": false
        }
      ],
      // Applies to miners only when direct Dogecoin Stratum is enabled.
      "banning": {
        "enabled": true,
        "checkThreshold": 50,
        "invalidPercent": 50,
        "time": 600
      },
      // Auxiliary block reconciliation and DOGE SOLO payouts.
      // This object is required even when the pool is disabled; set enabled=false
      // instead of removing it or replacing it with null.
      "paymentProcessing": {
        // Must remain enabled so AuxPoW blocks mature, credit and pay normally.
        // When this pool pays transaction fees, fund this exact wallet with a confirmed
        // reserve; minersPayTxFees covers normal sendmany fees but per-recipient fallback
        // submissions can still require additional spendable input.
        // See docs/operations.md#fee-reserve-and-balance-readiness.
        "enabled": true,
        // Smallest automatic payout, denominated in whole DOGE.
        "minimumPayment": 1.0,
        "payoutScheme": "SOLO"
      }
    },
    {
      // Bitcoin SOLO defaults to direct coinbase settlement in v0.3.0. See
      // examples/bitcoin_pool.json for separate low/high difficulty ports and a
      // smaller standalone configuration.
      // Keep SOLO unless the migrations, reserve and docs/pps.md checklist are complete.
      "id": "bitcoin-solo",
      "enabled": false,
      "coin": "bitcoin",
      // Retained for historical custodial blocks and daemon validation. New direct
      // blocks pay the address supplied by each authorized miner.
      "address": "CHANGE_ME_BITCOIN_POOL_WALLET_ADDRESS",
      "soloCoinbasePayout": true,
      // Keep staged ports disabled until this pool is configured and intentionally enabled.
      "enableInternalStratum": false,
      "blockRefreshInterval": 1000,
      "jobRebroadcastTimeout": 10,
      "clientConnectionTimeout": 600,
      "rewardRecipients": [
        {
          "address": "CHANGE_ME_BITCOIN_OPTIONAL_REWARD_RECIPIENT_ADDRESS",
          "percentage": 0
        }
      ],
      "ports": {
        "3052": {
          "name": "BTC-LOW-DIFF-DISABLED",
          "listenAddress": "127.0.0.1",
          "difficulty": 8192,
          "varDiff": {
            "minDiff": 4096,
            "maxDiff": null,
            "maxDelta": null,
            "targetTime": 15,
            "retargetTime": 90,
            "variancePercent": 30
          }
        },
        "3053": {
          "name": "BTC-HIGH-DIFF-DISABLED",
          "listenAddress": "127.0.0.1",
          "difficulty": 1048576,
          "varDiff": {
            "minDiff": 524288,
            "maxDiff": null,
            "maxDelta": null,
            "targetTime": 15,
            "retargetTime": 90,
            "variancePercent": 30
          }
        }
      },
      "daemons": [
        {
          "host": "127.0.0.1",
          "port": 8332,
          "user": "CHANGE_ME_BITCOIN_RPC_USER",
          "password": "CHANGE_ME_BITCOIN_RPC_PASSWORD",
          // Optional: must exactly match bitcoin.conf's zmqpubhashblock endpoint.
          // "zmqBlockNotifySocket": "tcp://127.0.0.1:28332",
          "ssl": false,
          "http2": false
        }
      ],
      "banning": {
        "enabled": true,
        "checkThreshold": 50,
        "invalidPercent": 50,
        "time": 600
      },
      // Required even while the pool is disabled. Direct SOLO requires both this
      // switch and cluster payment processing, plus the direct-settlement schema.
      "paymentProcessing": {
        "enabled": false,
        "minimumPayment": 0.001,
        "payoutScheme": "SOLO"
      }
    }
  ]
}