Run an Animica mining pool

The whole pool is one Python process — python -m animica.stratum_pool, run by the systemd unit animica-pool.service. That single process owns all three sockets, talks to your node over loopback JSON-RPC, and writes accounting to a local SQLite file. Everything else (web front-end, platform API, rig-rental) is a companion service behind nginx.

The raw stratum ports 3333 and 3334 bind 0.0.0.0 directly on the Python process — they are not proxied by nginx. Only the read-only stats API (:8550) and the web apps sit behind nginx.

• A fully-synced Animica mainnet node exposing RPC at http://127.0.0.1:8545/rpc. On the live host this is the docker container animica-mainnet-node publishing 8545 on loopback. The pool polls it for block templates (miner.getBlockTemplate) and submits found blocks (miner.submitBlock). If the node is behind, the pool mines a stale tip and finds nothing.
• The Animica package on the box — the live pool runs from the repo checkout at /root/animica via its venv (/root/animica/.venv), not from site-packages. For a fresh install: pip install --upgrade animica gives you the same animica.stratum_pool module and the animica CLI.
• A pool hot wallet — one Animica (anim1…, ML-DSA-65) address that receives every mined coinbase and signs payouts. Section 03.
• (Optional) a pruned monerod for XMR dual-mining, with restricted RPC on 127.0.0.1:18081. Section 09.
• A domain, DNS and TLS — an A record for your pool host, a Let's Encrypt cert, and firewall rules that let miners reach 3333/3334. Section 10.

$ curl -s http://127.0.0.1:8545/rpc \
    -d '{"jsonrpc":"2.0","id":1,"method":"chain.getHead","params":[]}' \
    -H 'content-type: application/json' | jq .result.height

Every ANM block your pool finds pays its full coinbase on-chain to one address — your pool hot wallet (ANIMICA_POOL_ADDRESS). The same wallet signs the payouts that go back out to miners. So this one key controls all pooled funds.

# Generates an ml_dsa_65 (0x1003) keypair + bech32m anim1 address.
$ animica wallet create --name pool-hot
# → address: anim1zqp...   seed phrase: (24 words — WRITE DOWN, KEEP OFFLINE)

You need two addresses if you want a real operator cut (see Fees): the pool wallet, and a separate fee/treasury wallet you control. Keep both seeds offline. For XMR you also register a Monero receive address.

The unit loads two config layers: the checked-in ops/profiles/mainnet.env (sourced by run.sh) and your per-machine overrides in /etc/animica/pool.env (EnvironmentFile). Everything below is an environment variable; there are no secrets here. This is the live mainnet configuration, annotated.

# ── Identity / coinbase ─────────────────────────────
ANIMICA_POOL_MODE=pps                     # pps | solo | both
ANIMICA_POOL_ADDRESS=anim1zqpkpp780…ws44wt   # coinbase + hot wallet (required)
ANIMICA_POOL_PAYOUT_WALLET=anim1zqpkpp780…ws44wt # signs payouts; defaults to POOL_ADDRESS

# ── Node RPC ────────────────────────────────────────
ANIMICA_RPC_URL=http://127.0.0.1:8545/rpc

# ── Stratum binds (raw TCP, NOT nginx) ──────────────
ANIMICA_STRATUM_BIND=0.0.0.0:3333          # pps + xmr (single-port detect)
ANIMICA_STRATUM_SOLO_BIND=0.0.0.0:3334     # true-solo listener
ANIMICA_POOL_API_BIND=127.0.0.1:8550       # stats API — keep loopback

# ── Fees (the only percentage levers) ───────────────
ANIMICA_POOL_ENA_FEE_BPS=0                 # PPS skim, bps. 0 = miners keep 100%
ANIMICA_POOL_ENA_TREASURY_ADDRESS=anim1zqp6ew0…qnpr2 # where the skim is paid
ANIMICA_POOL_SOLO_FEE_BPS=500              # 5% solo fee (see §08 caveat)

# ── Payout scheduler ────────────────────────────────
ANIMICA_POOL_PAYOUT_INTERVAL_SECONDS=900    # 15 min; 0 disables auto-payout
# ANIMICA_POOL_PAYOUT_MIN_AMOUNT=1               # nANM threshold (default 1)
# ANIMICA_POOL_PAYOUT_MAX_RECIPIENTS=100         # per-cycle cap

# ── Share difficulty (pinned for xmrig-compat) ──────
ANIMICA_STRATUM_MIN_DIFFICULTY=1.0
ANIMICA_STRATUM_MAX_DIFFICULTY=1.0
ANIMICA_STRATUM_SHARE_DIFFICULTY_FLOOR=1.0 # never emit set_difficulty < 1.0

# ── Monero dual-mining ──────────────────────────────
ANIMICA_POOL_XMR_ENABLED=1
ANIMICA_POOL_MONEROD_URL=http://127.0.0.1:18081
ANIMICA_POOL_XMR_ADDRESS=49RcNPVM…rXfJ        # pool's Monero receive addr

# ── Safety rails ────────────────────────────────────
ANIMICA_POOL_CREDIT_CAP_ENABLED=1          # credited can't outrun mined coinbase

The unit is a thin wrapper: it sources the mainnet profile, activates the venv, and launches the module. One process, restart-always.

[Service]
WorkingDirectory=/root/animica
Environment=PYTHONUNBUFFERED=1 HOME=/root PYTHONPATH=/root/animica/python:/root/animica
EnvironmentFile=-/etc/animica/pool.env          # leading '-' = optional
ExecStart=/root/animica/ops/run.sh --profile mainnet pool
Restart=always
RestartSec=5
KillSignal=SIGINT

$ systemctl start   animica-pool.service
$ systemctl restart animica-pool.service     # after any pool.env edit
$ systemctl status  animica-pool.service
$ journalctl -u animica-pool.service -f      # stratum + API logs (journald)

Animica's native PoW is SHA3-256 over the canonical CBOR block header — a share is accepted when int256(sha3_256(header)) ≤ target. The protocol is a custom object-based JSON-RPC (a hashshare proof), so stock xmrig can't mine the SHA3 side — miners use the animica CLI or the Animica xmrig fork. Stock xmrig can mine the Monero side on the same port.

Authentication username = your address

There is no account system. The Stratum username is the miner's anim1 payout address, optionally suffixed with a worker label using ., /, or : — e.g. anim1zqp…abc.rig-01. The password is not a secret; it's only read for an optional pps/solo mode hint, so any value (x) works. A submit whose address doesn't start with anim1 is rejected.

Ports recap

Share difficulty is pinned

Live config pins min = max = 1.0 with a 1.0 wire floor. The floor exists because some xmrig builds disconnect on a sub-1.0 set_difficulty. The server's own per-session vardiff is disabled — every accepted share is effectively a block-finder share at the network threshold θ. Do not lower the share target below 1.0.

Payouts are automatic and on-chain, run by a background PoolPayoutScheduler — not an API endpoint. It only starts when ANIMICA_POOL_PAYOUT_INTERVAL_SECONDS > 0 (live: 900 = 15 min).

How PPS credit works

Each accepted share credits reward × credit_fraction, where credit_fraction is the probability that share also solves a block — i.e. shares are priced at expected value, with no full-reward bonus for the winning share. Summed over a block, per-share credits total ~one block reward, so miners collectively receive ~100% of mined coinbase (minus any fee). This is self-limiting by design.

Each cycle, the scheduler…

1. Computes each address's owed = total_credit − paid_out from pool.db.
2. Caps the cycle to the net-unpaid mined budget (Σ block rewards − Σ payouts); if there isn't enough, it pro-rates. A cycle never pays out more than the pool actually mined.
3. Drops anyone below the min threshold (1 nANM default) and caps at 100 recipients per cycle.
4. Re-resolves a mempool-aware nonce fresh per tx and per retry, signs from the payout wallet, broadcasts, and records a payouts row (status=submitted). Retries up to 3× with backoff; nonce_gap is retryable.
5. A reconcile loop rebroadcasts dropped txs and releases credit (rolls back paid_out) if a tx is confirmed-dropped — with a timestamp cutoff to avoid double-paying grandfathered payouts.

pool.db — the ledger sqlite:////root/.animica/chain-1/pool.db

This is the part most guides hand-wave. Here is the honest, code-verified picture. First, the physical reality of where the money is:

The three fee levers

1. PPS percentage fee — ANIMICA_POOL_ENA_FEE_BPS (this is the real one). Basis points skimmed off every PPS credit before it reaches the miner. It accrues to ANIMICA_POOL_ENA_TREASURY_ADDRESS and the normal scheduler auto-pays it there each cycle. It's named for the ENA training treasury, but functionally it's just "skim N bps to an address you choose." Point the treasury address at your own operator wallet and set a nonzero bps — that is your working, auto-paid pool fee. Range 0–10000 bps. Live value is 0 (miners keep 100%; it was 3000 = 30% until 2026-07-08).

# in /etc/animica/pool.env
ANIMICA_POOL_ENA_FEE_BPS=150                    # 150 bps = 1.5%
ANIMICA_POOL_ENA_TREASURY_ADDRESS=anim1<your-fee-wallet>
$ systemctl restart animica-pool.service

2. Solo-port fee — ANIMICA_POOL_SOLO_FEE_BPS (default 500 = 5%). Intended to keep 5% of a solo-found block, paying the finder 95%.

3. XMR dual-mine fee — hardcoded 5%. On the Monero side, POOL_FEE_BPS = 500 of every block reward (plus rounding dust) stays at your pool's Monero address; 95% is owed to miners and paid via monero-wallet-rpc. Section 09.

Withdrawing your fee / margin

There is no operator withdraw command, API, or auto-pay-to-operator step for the ANM side (grep for withdraw/take_fee in the pool code returns nothing). Both your skim (if the treasury address is your own) and any uncredited margin live in the pool hot wallet on-chain. You take them out with an ordinary signed transaction:

$ animica wallet send \
    --from  anim1<pool-hot-address> \
    --to    anim1<your-cold-wallet> \
    --amount 250                          # ANM (1 ANM = 1e9 nANM)
# signs with your offline key — the pool process never sees it.

Dual-mining lets stock xmrig point at your pool and mine Monero (RandomX, rx/0) for extra yield. It runs in single-port mode: a client that sends a cryptonote {"method":"login"} on its first line to :3333 is protocol-detected and routed to the XMR handler; everyone else stays on the SHA3 path — same port.

Requirements: a pruned monerod with restricted RPC on loopback, and a pool Monero receive address. The XMR login field must still be an anim1 address — XMR shares are attributed to the miner's Animica identity, and the miner registers a separate Monero payout address via the portal.

ExecStart=/usr/local/bin/monerod --data-dir=/var/lib/monero \
    --rpc-bind-ip=127.0.0.1 --rpc-bind-port=18081 --restricted-rpc \
    --p2p-bind-port=18080 --prune-blockchain --no-zmq \
    --log-file=/var/log/monerod.log

XMR payouts are not handled by the stratum process — a separate monero-wallet-rpc (default 127.0.0.1:18083) does the transfers, driven by an animica pool xmr-payout job on a cron, logging to /var/lib/animica-pool/xmr-payouts.jsonl. The pool's 5% stays at the pool Monero address; withdraw it the same way you'd move any Monero.

nginx fronts the web + API surface on 443; it does not touch the raw stratum ports. DNS is one A record for your pool host; certs are Let's Encrypt.

Route map longest ^~ prefix wins

$ ufw allow 3333/tcp    # pps + xmr
$ ufw allow 3334/tcp    # solo
$ ufw allow 443/tcp     # web / api (nginx)
# keep 8545, 8550, 18081 on loopback — never expose them

The :8550 API is read-only — pure stats and accounting, with no payout or withdraw route (by design). The public front-end and per-miner stats pages all read from it.

Front-ends: the Next.js web app at / (pages /mine, /miner lookup, /stats, /download), the Astro pool-web static site, and the rig-rental app at /app. Miners check their own numbers with no login at /miner by entering their address or worker name.

$ curl -s http://127.0.0.1:8550/api/pool/summary | jq
$ curl -s http://127.0.0.1:8550/api/pool/accounting | jq   # owed vs paid vs mined
$ curl -s http://127.0.0.1:8550/v1/pool/status | jq .payout_countdown_seconds

Give miners these three connection recipes. The username is always their own anim1 address; the password is a throwaway.

PPS · Animica SHA3

$ pip install --upgrade animica
$ animica miner mine-blocks --count 0 \
    --pool-stratum stratum+tcp://pool.animica.org:3333 \
    --address anim1<your-address>
# or the reference binary:
$ ./animica-miner --pool-url stratum+tcp://pool.animica.org:3333 \
    --address anim1… --worker rig-01 --pool-mode pps

Solo · finder credited

$ ./animica-miner --pool-url stratum+tcp://pool.animica.org:3334 \
    --address anim1… --worker rig-01 --pool-mode solo

XMR · stock xmrig (RandomX)

{ "pools": [{
    "url":  "pool.animica.org:3333",
    "algo": "rx/0",
    "user": "anim1<your-address>",   # XMR credited to your ANM identity
    "pass": "x",
    "tls":  false,
    "keepalive": true
}] }