/pogolo - decentralize or die/

solo db-less bitcoin-only mining pool, meant for lan swarms, not the internet;
start it, point your miners to it, and watch the logs roll by
think of this as public-pool but minimal and for self-sovereign nerds
infinite thanks to btcd for bitcoin tooling and public-pool for reference

want a go pool you can run on the public internet? check out https://github.com/Distortions81/M45-Core-goPool!

• features
• install
  • umbrel
  • docker
  • go
  • manual install

features

• set a default address to mine to, no more ctrl+c ctrl+v ctrl+v ctrl+v ctrl+v ctrl+v
• stratum v1 and stratum v2 on the same port
• colorful and detailed logs (respects NO_COLOR)
• read-only api
• zmq and btcd websocket support
• high performance and low memory usage (119k shares/sec @ ~50 mib + 1kib/client)

implemented BIPs

• 34
• 41 (probably)
• 54 (coinbase, relies on a compliant backend for the rest)
• 310 (minus subscribe-extranonce)
• 323

supported miners

• *axe family (bitaxe, nerd*axe, etc)
• cpuminer
• antminers
• braiins OS

supported backends

pogolo has no tls support.

• JSON-RPC (no longpoll)
• btcd websocket
• ZMQ (hashblock topic)

unsupported

• whatsminers (they dont mine on the provided jobs, if you have one please test and send logs)
• luckyminers/other non-foss axe clones
• multiple sv2 channels on one connection (for now)
• group channels (for now)

api

the api is documented in openapi.yaml, and exposed at /openapi.yaml.

install

umbrel

get pogolo from the umbrel app store: https://apps.umbrel.com/app/pogolo
then point your miners to stratum+tcp://umbrel.local:5661 or stratum2+tcp://umbrel.local:5661

docker

image at https://hub.docker.com/r/0xf0xx0/pogolo

copy the pogolo.toml from contrib/pkgs/docker, configure it to your needs, then run

docker run -d -v "./pogolo.toml:/config/pogolo.toml" 0xf0xx0/pogolo:latest

docker compose exists but likely needs tweaks, its also under contrib/pkgs/docker

environment overrides

for easy config

POGOLO_HOST: # overrides [pogolo].host
POGOLO_BACKEND_HOST: # overrides [backend].host
POGOLO_BACKEND_RPCAUTH: # overrides [backend].rpcauth
POGOLO_BACKEND_ZMQHOST: # overrides [backend].zmq_host

go

go install git.0xf0xx0.eth.limo/0xf0xx0/pogolo@latest

then follow manual install/configure.

manual install

build

git clone https://git.0xf0xx0.eth.limo/0xf0xx0/pogolo.git
cd pogolo
go build -trimpath -ldflags="-s -w -buildid="
go install

configure

# create config dir
mkdir "$XDG_CONFIG_HOME/pogolo"

# write embedded default config (preferred)
pogolo --writedefaultconf "$XDG_CONFIG_HOME/pogolo/pogolo.toml"
# OR copy the example config
cp contrib/pogolo.example.toml "$XDG_CONFIG_HOME/pogolo/pogolo.toml"

# configure interface, backend, and auth
vim "$XDG_CONFIG_HOME/pogolo/pogolo.toml"

# run
pogolo

theres a systemd unit at contrib/init/pogolo.service for bare installs
it expects pogolo to be in the system PATH, a bitcoin group, and a config file at /etc/pogolo/pogolo.toml.

sudo cp contrib/init/pogolo.service /etc/systemd/system/
sudo mkdir -p /etc/pogolo
pogolo --writedefaultconf /etc/pogolo/pogolo.toml
sudo chmod -R 755 /etc/pogolo
sudo chown -R :bitcoin /etc/pogolo 
sudo systemctl enable --now pogolo

miner config

host: stratum[2]+tcp://<your lan ip>:5661
username: [your onchain address][.<worker name>]
password: [required if set in pogolo.toml]
suggested diff: [optional]

the onchain address is also optional if the pool has a default configured.
shares submitted between job changes are normal, the expected error rate is <=0.2%.

benchmarking

to reproduce shares/s result:
benchmark with https://github.com/eandersson/open-pool-benchmark

TODO

• link stratum and mining docs
  waiting for bip 41
  https://web.archive.org/web/20201130051808/https://braiins.com/stratum-v1/docs
• prometheus metrics (half-done)
  • block submission metrics
• aur packages (under contrib/pkgs/arch, needs a maintainer)