Mining Operations

Run a Talero miner or pool node

The Talero miner role enables mining RPC methods and mining-oriented runtime behavior. This guide covers two safe deployment patterns: a private miner node and a pool-facing work server. It avoids publishing real allowlists, admin RPC ranges, or other sensitive infrastructure details.

Miner Pool-facing RPC Mainnet guard rails No public admin ACLs

Mainnet miner mode is intentionally guarded. The node refuses to start as a miner unless the operator explicitly sets TALERO_MINER_ACK_MAINNET=1 and provides a coinbase address.

Choose a mode

Mode	Use it when	Key setting
Private miner node	You control the miner and do not expose work RPC publicly.	Keep mining RPC private and use tight network exposure.
Pool-facing work server	You need `getWork` / `submitWork` for upstream pool infrastructure.	Expose only the intended mining edge, keep admin and trusted tiers private, and document public-safe quotas only.

The mining role enables mining RPC methods independently from the internal automatic block producer. That is why a pool-facing node can still use TALERO_DISABLE_MINING=1 while serving work RPC.

Requirements

A Linux host with persistent storage for /data.
Docker Engine and Docker Compose plugin.
The Talero node repository or release bundle.
Canonical mainnet identity material: TALERO_EXPECTED_CHAIN_ID, TALERO_EXPECTED_GENESIS_HASH, TALERO_GENESIS_TIMESTAMP_SECS, and the approved bootnode list.
A reward destination for TALERO_COINBASE.
A clear decision about whether the node runs private mining only or serves pool-facing work RPC.

Install Docker on Ubuntu

If the host is fresh, use Docker's official Ubuntu flow. For updates or distro-specific changes, verify against the official Docker Engine install guide for Ubuntu.

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo \"${UBUNTU_CODENAME:-$VERSION_CODENAME}\") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Prepare the deployment files

sudo mkdir -p /opt/talero
sudo chown "$USER":"$USER" /opt/talero
cd /opt/talero

# Place the Talero node release or repository here
# Required files include:
#   Dockerfile
#   docker-compose.mainnet.yml
#   docs/
#   tools/

cd /opt/talero/node
docker compose -f docker-compose.mainnet.yml build

Mainnet guards

Mining on mainnet requires more than the generic node startup checks. The code refuses to start in miner mode unless you explicitly acknowledge the role and set a coinbase address.

Set TALERO_MINER_ACK_MAINNET=1.
Set TALERO_COINBASE=tlro:0xYOUR_REWARD_ADDRESS.
Set the expected mainnet chain identity values.
Set the canonical bootnode list.

Miners also wait for peers by default when bootnodes are configured. Do not force solo-style behavior with emergency-only flags unless you are deliberately running an isolated rehearsal.

Ports and host mapping

If the miner or pool node shares a host with another Talero node, use distinct host ports. The example below maps host 8548 to container 8547 and host 30305 to container 30303.

cd /opt/talero/node
cat > docker-compose.mainnet.miner-ports.yml <<'EOF'
services:
  talero-node:
    ports:
      - "127.0.0.1:8548:8547"
      - "30305:30303"
      - "30305:30303/udp"
EOF

This keeps RPC local to the host while exposing the P2P address on a dedicated public port. If you build a public mining edge, do it through a deliberate front-end or reverse proxy, not by publishing unrestricted raw node RPC.

Create the miner environment file

cd /opt/talero/node
cat > .env.mainnet.miner <<'EOF'
TALERO_NETWORK=mainnet
TALERO_ROLE=miner
TALERO_ROLE_STRICT=1
TALERO_MINER_ACK_MAINNET=1

# Canonical chain identity from the approved mainnet release process
TALERO_EXPECTED_CHAIN_ID=REPLACE_WITH_CHAIN_ID
TALERO_EXPECTED_GENESIS_HASH=0xREPLACE_WITH_CANONICAL_GENESIS_HASH
TALERO_GENESIS_TIMESTAMP_SECS=REPLACE_WITH_CANONICAL_GENESIS_TIMESTAMP

# Reward destination
TALERO_COINBASE=tlro:0xYOUR_REWARD_ADDRESS

# RPC inside the container
TALERO_RPC_LISTEN=0.0.0.0:8547
TALERO_RPC_PUBLIC_MODE=1
TALERO_RPC_READONLY=0
TALERO_RPC_MINING_PUBLIC_ENABLED=0
TALERO_RPC_TRUST_X_FORWARDED_FOR=0

# P2P
TALERO_P2P_LISTEN=0.0.0.0:30303
TALERO_P2P_SELF_ADDR=YOUR_PUBLIC_IP:30305
TALERO_BOOTNODES=BOOTNODE_A:30303,BOOTNODE_B:30303

# Mining mode
TALERO_DISABLE_MINING=1

# Runtime hardening
TALERO_EVM_ENABLED=1
TALERO_EVM_REPLAY_ON_STARTUP=1
TALERO_EVM_REPLAY_STRICT_STARTUP=1
TALERO_SAFE_MODE_ENABLED=1
TALERO_SAFE_MODE_MANUAL_OVERRIDE=auto
TALERO_LOG=info
TALERO_LOG_FORMAT=json
EOF

When to change `TALERO_DISABLE_MINING`

TALERO_DISABLE_MINING=1: recommended starting point for a pool-facing work server.
TALERO_DISABLE_MINING=0: use this if you intentionally want the internal producer active.

This guide intentionally omits concrete values for TALERO_RPC_ADMIN_CIDRS, TALERO_RPC_TRUSTED_CIDRS, TALERO_RPC_MINING_CIDRS, and trusted proxy CIDRs. Those are sensitive infrastructure controls and belong in private operations docs.

Mining RPC surfaces

The miner role enables mining RPC methods. The public-safe method overview is:

Method	Purpose	Notes
`eth_getWork`	Ethereum-style work template	Returns `[powHash, seedHash, boundary]`.
`talero_getWork`	Talero work template	Mining-oriented RPC for Talero work distribution.
`talero_submitWork`	Submit work result	Use this, not `eth_submitWork`.
`talero_miningStats`	Mining and rate-limit telemetry	Useful for pool dashboards and worker monitoring.

eth_submitWork is not supported. The node explicitly instructs callers to use talero_submitWork(jobId, nonce, mixHash) instead.

Start the miner or pool node

cd /opt/talero/node
TALERO_ENV_FILE=.env.mainnet.miner \
docker compose \
  -f docker-compose.mainnet.yml \
  -f docker-compose.mainnet.miner-ports.yml \
  up -d

cd /opt/talero/node
TALERO_ENV_FILE=.env.mainnet.miner \
docker compose \
  -f docker-compose.mainnet.yml \
  -f docker-compose.mainnet.miner-ports.yml \
  logs -f talero-node

Verify node health

curl -sS http://127.0.0.1:8548/health | jq '{
  ok,
  network,
  role,
  head,
  sync,
  p2p
}'

curl -sS -X POST http://127.0.0.1:8548/rpc \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"talero_miningStats","params":{}}' | jq '.result'

curl -sS -X POST http://127.0.0.1:8548/rpc \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_getWork","params":[]}'

role should be "miner".
talero_miningStats.enabled should be true.
publicMiningEnabled should match your intended exposure model.
If the node is waiting for peers, confirm bootnodes and P2P reachability before forcing anything.

Upgrade flow

cd /opt/talero/node
tar -C ./data -czf miner-backup-$(date -u +%Y%m%d-%H%M%S).tgz .

docker compose -f docker-compose.mainnet.yml build

TALERO_ENV_FILE=.env.mainnet.miner \
docker compose \
  -f docker-compose.mainnet.yml \
  -f docker-compose.mainnet.miner-ports.yml \
  up -d

Troubleshooting

Error shape	Likely cause	Fix
`requires TALERO_MINER_ACK_MAINNET=1`	Miner mode was not explicitly acknowledged.	Set `TALERO_MINER_ACK_MAINNET=1`.
`mainnet miner mode requires TALERO_COINBASE`	No coinbase address was configured.	Set a valid reward destination.
`Method not found` for mining RPC	The node is not running in miner role.	Set `TALERO_ROLE=miner` and restart.
Mining stays paused waiting for peers	Bootnodes are configured but the node has not reached the network yet.	Fix P2P connectivity instead of forcing solo behavior.

cd /opt/talero/node
TALERO_ENV_FILE=.env.mainnet.miner \
docker compose \
  -f docker-compose.mainnet.yml \
  -f docker-compose.mainnet.miner-ports.yml \
  logs --tail=200 talero-node