DATUM in a box — build your own blocks

1 · Get a machine

A spare PC or laptop running Linux works, as long as it stays on. So does a small VPSi×VPS = virtual private server: a small computer you rent by the month from a hosting company and control over the internet. Any provider you already use is fine. from any provider you like. If you’re installing the operating system fresh, pick Ubuntu 26.04; any current Ubuntu or Debian works.

If the machine isn’t in front of you, open a terminal (on Windows: PowerShell; on Mac: Terminal) and log in to it with SSHi×SSH is the standard way to type commands on a remote Linux machine. It is built into Windows 10/11, macOS and Linux. The provider's page tells you the user name and password or key to use.:

ssh ubuntu@YOUR-MACHINE-IP        # user name is often ubuntu, root or debian

Everything from here on is typed into that terminal. If a command starts with sudoi×sudo runs one command as the administrator ('root'). Installing programs and creating services needs it. It may ask for your login password the first time. it may ask for your password once.

2 · Run the setup script

Two lines: download the script, run it. Copy the block with the button and paste it into the terminal.

curl -fsSLo setup-datum.sh https://raw.githubusercontent.com/bitcoinxor/datum-in-a-box/v1.7.4/setup-datum.sh
sudo bash setup-datum.sh

The script is open source — read it on GitHub at github.com/bitcoinxor/datum-in-a-box. It installs Bitcoin Knots v29.4.2.knots20260508 and ratum-gateway 0.1.28 from their official releases, checks every download against its checksumi×A checksum is a fingerprint of a file published by its authors. The script computes the fingerprint of what it downloaded and refuses to install anything that doesn't match, so a corrupted or tampered download can't get through., and refuses to continue if anything doesn’t match. It never deletes chain data; running it again later just updates.

3 · Answer the questions

• Your payout address — where every block pays you. It must be a wallet you hold the keys to, not an exchange deposit address. No wallet yet? Set one up first, it takes ten minutes. The script checks the address character by character — a typo is caught before anything starts.
• A name for your blocks — up to 60 letters. Every block you help find is stamped “Bitcoin Xor” plus your name, on-chaini×Written into the block itself, in the coinbase transaction, so it is part of the blockchain's permanent record and visible in any block explorer., forever.
• Which DATUM pool — press Enter for Bitcoin Xor, then Enter again for the default endpoint (datum.xorpool.com, United States). If your machine is in Asia or Europe you can type hk.datum.xorpool.com or eu.datum.xorpool.com instead. The script also works with any other DATUM pool: choose option 2 and paste that pool’s host:port and public keyi×All three are the same pool and the same payout; the HK and EU ones are relays closer to you. It only affects the gateway's link to the pool, which isn't latency-sensitive, so the default is fine for most people..
• Skip the initial sync? — press Enter for yes. It downloads a snapshot of the chain (~10 GB) so the node starts at the tip in minutes instead of 1–3 daysi×A snapshot is a copy of our node's verified chain data (pruned, so ~10 GB). Your node checks it against the published checksum, starts from it, and verifies every block after it itself - the same trust model as any blockchain bootstrap. Say no if you'd rather your node verify all of history from block 0..

It then shows a summary; type y and it installs. Two or three minutes later you see Done and the address to point your miners at.

4 · Point your ASICs at your gateway

On each miner’s settings page (Goldshell, Antminer, etc.), set the pool to your machine, not to xorpool.com. The script printed the exact line; it looks like this:

The word before the dot can be anything; the part after it is the worker namei×A label for that particular machine, so you can tell your rigs apart in the stats. rig1, shed-left, whatever you like. you’ll see in stats. Your payout address is already in the gateway, so the miner never needs it.

5 · Wait for the node to sync

If you took the snapshot, the node is at the tip within a few minutes of the download finishing and your ASICs start getting work right away. If you said no, the node has to download and check the whole chain oncei×Called the initial sync. A new node starts from the very first block and verifies every block since. Afterwards it only needs the new block every few minutes. — 1–3 days on a small VPS. Either way: leave the machine on, nothing to do; your ASICs can stay pointed at it and get work automatically the moment the node reaches the tip.

Check on it any time by logging in and typing:

datum-status

It shows the sync percentage, then at tipi×'The tip' is the newest block on the chain. A node at the tip is fully caught up and can build templates for your miners., then your hashrate and accepted shares once the miners are working. From then on your address appears at xorpool.com/datum/miner/<your address> with your share of every block.

Changed your mind about the snapshot? Re-run the script and answer Y; it keeps everything else.

6 · That’s it — and if something’s off

• Everything restarts by itself, including after a reboot.
• To update later (new Knots or ratum release), run the same three lines from step 2 again.
• ASICs say they can’t connect — the gateway listens on port 23334. If the machine or your provider has a firewall, allow that port from your miners.
• Miners connected but 0 hashrate on the pool — the node isn’t at the tip yet. datum-status shows the percentage.
• Anything else: Telegram, paste the output of datum-status and we’ll sort it.

1 · A Windows PC that stays on

Windows 10 or 11, 64-bit, any PC that stays on and doesn’t sleep (Settings → System → Power: set sleep to Never while plugged in). The node and gateway run in the background as scheduled tasks that start with Windows, no login needed.

Your ASICs must be on the same network as the PC (or able to reach it). The script adds the one firewall rule needed (port 23334, private networks).

Already running the Bitcoin Knots wallet on that PC? Keep it. The script notices it and offers to install only the gateway, using your node: two lines go into its bitcoin.conf (RPC on, block notify; a backup is kept), the gateway logs in with the node’s cookie file, and mining happens while the wallet is open.

2 · Run the setup script in PowerShell (as administrator)

Press the Windows key, type PowerShell, right-click it and choose Run as administrator. Then paste these three lines:

cd $env:USERPROFILE\Downloads
Invoke-WebRequest https://raw.githubusercontent.com/bitcoinxor/datum-in-a-box/v1.7.4/setup-datum.ps1 -OutFile setup-datum.ps1
powershell -ExecutionPolicy Bypass -File .\setup-datum.ps1

The script is open source — read it on GitHub at github.com/bitcoinxor/datum-in-a-box. It installs Bitcoin Knots v29.4.2.knots20260508 and ratum-gateway 0.1.28 from their official Windows builds into C:\XorDatum, checks every download against its checksum and refuses to continue if anything doesn’t match. Re-running it later updates in place; chain data is kept.

3 · Answer the questions

The same questions as the Linux script: your payout address (a wallet you hold the keys to, never an exchange deposit address — typos are caught before anything starts), a name for your blocks, the pool endpoint (Enter for the default), and whether to skip the initial sync with the chain snapshot (Enter for yes — about 12 GB, then the node is at the tip in minutes). It shows a summary; type y.

4 · Point your ASICs at the PC

The script prints the PC’s address at the end. On each miner:

The word before the dot can be anything; the part after it is the worker name. Your payout address is already in the gateway.

5 · Check on it

Any time, in PowerShell:

powershell -ExecutionPolicy Bypass -File C:\XorDatum\datum-status.ps1

It shows the node’s sync progress, then at tip, then your hashrate and shares. Your address then appears at xorpool.com/datum/miner/<your address>.

Logs: C:\XorDatum\logs\gateway.log and C:\XorDatum\node\debug.log. To update later, run the same three lines again. Xor Desk (the local dashboard, beta) is Linux-only for now; Windows support is next.

1 · A Mac that stays on

Any Mac on macOS 12 or newer, Apple silicon or Intel, that stays on and plugged in. A Mac mini is ideal. The node and gateway run as launchd system servicesi×launchd is the part of macOS that starts and supervises background programs. A system service starts at boot, before anyone logs in, and is restarted if it stops. that start at boot, no login needed.

The script offers to set the Mac to never sleep while plugged in (a sleeping Mac stops mining). Your ASICs must be on the same network as the Mac or able to reach it.

2 · Run the setup script in Terminal

Open Terminal (Applications → Utilities, or search for it with Spotlight) and paste these two lines. It asks for your login password once, for sudo.

curl -fsSLo setup-datum-macos.sh https://raw.githubusercontent.com/bitcoinxor/datum-in-a-box/v1.7.4/setup-datum-macos.sh
sudo bash setup-datum-macos.sh

The script is open source — read it on GitHub at github.com/bitcoinxor/datum-in-a-box. It installs Bitcoin Knots v29.4.2.knots20260508 and ratum-gateway 0.1.28 from their official macOS builds into /usr/local/xordatum, checks every download against its checksum, and needs nothing installed first: no Homebrew, no Xcode tools, no Python. It never deletes chain data; running it again later just updates.

3 · Answer the questions

The same questions as the Linux script: your payout address (a wallet you hold the keys to, never an exchange deposit address — typos are caught before anything starts), a name for your blocks, the pool endpoint (Enter for the default), whether to skip the initial sync with the chain snapshoti×A copy of the pruned chain, published every two days. With it the node starts at the tip in minutes instead of syncing for 1-3 days. It needs a tar that reads zstd (recent macOS has one) or Homebrew's zstd; otherwise the script says so and the node syncs from scratch., and whether to keep the Mac awake while plugged in. Then a summary, and it installs.

If macOS asks whether bitcoind or ratum-gateway may accept incoming connections, click Allow: that is your ASICs reaching the gateway.

4 · Point your ASICs at the Mac

The script prints the Mac’s address at the end. On each miner:

The word before the dot can be anything; the part after it is the worker name. Your payout address is already in the gateway.

5 · Check on it

Any time, in Terminal:

datum-status

It shows the node’s sync progress, then at tip, then your hashrate and shares. Your address then appears at xorpool.com/datum/miner/<your address>.

Logs: /usr/local/xordatum/logs/gateway.log and /usr/local/xordatum/node/debug.log. To update later, run the same two lines again. Xor Desk (the local dashboard, beta) is Linux-only for now.

1 · Get a machine

A spare Linux box or a small VPS — anything that stays on. The node is pruned, so it stays small once synced.

Everything below assumes an Ubuntu or Debian machine you can sudo on. Run the cards in order; each card is one batch and the copy button takes the whole card.

Updates, and a service useri×A dedicated Linux user with no login shell that the node and gateway run as. If either program ever misbehaves it can only touch its own files, not the rest of the machine. for the two programs to run as:

sudo apt update && sudo apt -y upgrade && sudo apt -y install curl
sudo useradd -r -m -d /var/lib/knots -s /usr/sbin/nologin knots

This guide doesn’t set up a firewall. If your machine or provider has one, the only port that needs to be reachable is 23334 (the gateway), and only from your miners. The node’s RPC only listens on the machine itself.

2 · Install Bitcoin Knots (BLAKE2b fork)

The chain runs on Bitcoin Knots v29.4.2.knots20260508 — use that exact release from github.com/bitcoinknots/bitcoin/releases/tag/v29.4.2.knots20260508. Older builds don’t know the fork’s proof of work. This picks the right build for your CPU and verifies the checksumi×A fingerprint of the file published by the authors. sha256sum recomputes it from your download and prints OK only if they match.:

cd /tmp
V=29.4.2.knots20260508; A=$(uname -m | sed 's/x86_64/x86_64-linux-gnu/; s/aarch64/aarch64-linux-gnu/')
curl -LO https://github.com/bitcoinknots/bitcoin/releases/download/v$V/bitcoin-$V-$A.tar.gz
curl -LO https://github.com/bitcoinknots/bitcoin/releases/download/v$V/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS          # must print: bitcoin-...tar.gz: OK
tar xzf bitcoin-$V-$A.tar.gz
sudo install -m 755 bitcoin-$V/bin/bitcoind bitcoin-$V/bin/bitcoin-cli /usr/local/bin/
bitcoind --version | head -1                        # Bitcoin Knots daemon version v29.4.2.knots20260508

Signing keys for a full gpg --verify SHA256SUMS.asc are on the release page if you want the extra check.

3 · Configure and sync the node

This writes the node config, installs it as a servicei×A systemd service is how Linux keeps a program running in the background: it starts at boot, restarts if it crashes, and you control it with systemctl. and starts it. Change the RPCi×RPC is the node's local control interface. The gateway uses it to ask for block templates and to submit found blocks. It is bound to 127.0.0.1, so only programs on this machine can reach it. password on the rpcpassword= line to anything long and random before you paste (you’ll use it again in step 4):

sudo -u knots tee /var/lib/knots/bitcoin.conf >/dev/null <<'EOF'
# /var/lib/knots/bitcoin.conf - Bitcoin Knots (BLAKE2b fork), pruned, for a DATUM gateway
server=1
disablewallet=1
prune=2000
txindex=0
dbcache=2000            # speeds up the first sync; lower to 400 afterwards if RAM is tight
maxmempool=200
# RPC - local only; the gateway logs in with these
rpcbind=127.0.0.1
rpcallowip=127.0.0.1
rpcuser=knots
rpcpassword=CHANGE-ME-to-a-long-random-string
# Peers: the fork has no DNS seeds of its own, so start from the pool's public nodes and let gossip do the rest
dnsseed=0
fixedseeds=0
addnode=stratum.xorpool.com:18901
addnode=datum.xorpool.com:8333
# Tell the gateway the instant a new block arrives (keeps your miners off stale work)
blocknotify=/usr/bin/pkill -USR1 ratum-gateway
EOF
sudo tee /etc/systemd/system/knotsd.service >/dev/null <<'EOF'
[Unit]
Description=Bitcoin Knots (BLAKE2b fork, pruned)
After=network-online.target
Wants=network-online.target

[Service]
User=knots
Group=knots
ExecStart=/usr/local/bin/bitcoind -datadir=/var/lib/knots -conf=/var/lib/knots/bitcoin.conf
Restart=on-failure
RestartSec=5
TimeoutStopSec=180

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload && sudo systemctl enable --now knotsd

It now syncs the chain from the beginningi×prune=2000 keeps only the newest ~2 GB of raw blocks on disk once they're verified, so the node stays ~14 GB instead of hundreds. The two addnode lines are how it finds the fork's network: the fork has no DNS seeds, so it starts from the pool's public nodes and learns the rest from them.. Check progress any time with:

sudo -u knots bitcoin-cli -datadir=/var/lib/knots getblockchaininfo | grep -E 'blocks|verificationprogress'

From scratch this takes 1–3 days on a 2-core VPS (the full Bitcoin history up to the fork, plus the fork blocks). It runs unattended, and you can do step 4 meanwhile. Or skip it with the snapshot — a copy of our node’s verified pruned chain (~10 GB)i×Same trust model as any blockchain bootstrap: you trust this copy of history up to the snapshot height, verify its checksum, and your node verifies every block after it. The published block hash lets you cross-check against any explorer.. This fetches it, verifies the checksum, swaps it in and confirms the block hash:

cd /var/tmp && curl -fsS https://snapshot.xorpool.com/latest.json -o latest.json
F=$(python3 -c 'import json;print(json.load(open("latest.json"))["file"]')
curl -fL -C - -o $F https://snapshot.xorpool.com/$F
echo "$(python3 -c 'import json;print(json.load(open("latest.json"))["sha256"]')  $F" | sha256sum -c   # must print: OK - stop here if it doesn't
sudo apt -y install zstd
sudo systemctl stop knotsd && sudo rm -rf /var/lib/knots/blocks /var/lib/knots/chainstate
sudo tar -C /var/lib/knots --use-compress-program=unzstd -xf $F && sudo chown -R knots:knots /var/lib/knots
sudo systemctl start knotsd && rm -f $F
H=$(python3 -c 'import json;print(json.load(open("latest.json"))["height"]'); sleep 20
sudo -u knots bitcoin-cli -datadir=/var/lib/knots getblockhash $H; python3 -c 'import json;print(json.load(open("latest.json"))["block_hash"]')   # the two hashes must match

The node is then at the tip within a couple of minutes. The snapshot is rebuilt every two days; latest.json always names the current one.

4 · Install the DATUM gateway (ratum)

ratum-gateway is an open-source (AGPL) DATUM gateway written for this chain: it builds templates from your node and speaks the 164-byte v2 header to BLAKE2b hardware over Stratumi×Stratum is the protocol ASICs use to talk to a pool or gateway: the gateway sends work, the miner sends back shares (near-misses that prove it is working) and, now and then, a real block.. Prebuilt static binaries are on the release page; this fetches the right one and verifies it:

cd /tmp
R=0.1.28; A=$(uname -m | sed 's/x86_64/x86_64-linux-musl/; s/aarch64/aarch64-linux-musl/')
curl -LO https://github.com/iohzrd/ratum/releases/download/v$R/ratum-gateway-$R-$A.tar.gz
curl -LO https://github.com/iohzrd/ratum/releases/download/v$R/ratum-gateway-$R-$A.tar.gz.sha256
sha256sum -c ratum-gateway-$R-$A.tar.gz.sha256      # must print: OK
tar xzf ratum-gateway-$R-$A.tar.gz
sudo install -m 755 $(find . -name ratum-gateway -type f | head -1) /usr/local/bin/ratum-gateway
ratum-gateway --version

Now the config. Three things are yours to change before you paste — everything else already points at this pool:

• rpcpassword — the password you put in bitcoin.conf in step 3.
• mining.pool_address — your own address (a wallet you hold the keys to, not an exchange). This is where every block pays you.
• coinbase_tag_secondary — your name, up to 60 characters. Blocks you help find are stamped Bitcoin Xor plus this, on-chain, forever. Put the same name in coinbase_tag_primary.

sudo mkdir -p /etc/ratum
sudo tee /etc/ratum/gateway.json >/dev/null <<'EOF'
{
  "bitcoind": {
    "rpcurl": "http://127.0.0.1:8332",
    "rpcuser": "knots",
    "rpcpassword": "the-same-password-as-in-bitcoin.conf",
    "work_update_seconds": 40,
    "notify_fallback": true
  },
  "mining": {
    "pool_address": "bc1qYOUR-OWN-ADDRESS",
    "coinbase_tag_primary": "YOUR NAME",
    "coinbase_tag_secondary": "YOUR NAME"
  },
  "stratum": {
    "listen_addr": "0.0.0.0",
    "listen_port": 23334
  },
  "datum": {
    "pool_host": "datum.xorpool.com",
    "pool_port": 28915,
    "pool_pubkey": "b83aedbba54ba2aa605c76859d97aebd16dece3284402b9fc874778a974da4acbb449f6ccda61625d700036f0487a05f5184f79a07abf2880da77352f4cc487e",
    "pool_url": "https://xorpool.com/datum",
    "pool_pass_full_users": false,
    "pool_pass_workers": true,
    "gateway_fee_bps": 0,
    "pooled_mining_only": true
  },
  "api": {
    "listen_addr": "127.0.0.1",
    "listen_port": 8000
  }
}
EOF
sudo chown -R knots:knots /etc/ratum && sudo chmod 640 /etc/ratum/gateway.json
sudo tee /etc/systemd/system/ratum-gateway.service >/dev/null <<'EOF'
[Unit]
Description=ratum-gateway (DATUM, stratum 23334)
After=network-online.target knotsd.service
Wants=network-online.target

[Service]
User=knots
Group=knots
ExecStart=/usr/local/bin/ratum-gateway -c /etc/ratum/gateway.json
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload && sudo systemctl enable --now ratum-gateway
sleep 3; journalctl -u ratum-gateway -n 20 --no-pager

The last line prints the gateway’s first log lines; you want to see the pool handshake:

INFO  [ratum_gateway::datum] connecting to DATUM pool datum.xorpool.com:28915
INFO  [ratum_gateway::datum] DATUM pool configuration: prime_id 0x00000001, tag "Bitcoin Xor", min diff ...
INFO  [ratum_gateway::datum] DATUM pool anti-block-withholding: enabled

Once the node is at the tip you’ll also see Stratum job ... ready lines every ~40 s and on every new block. Until then it says it’s waiting for the node — that’s normal.

What the keys mean: pool_pass_workers credits all your work to pool_address and passes each ASIC’s worker name for stats. (Set pool_pass_full_users: true instead if each ASIC should be paid to its own address — then the ASIC username must be that address.) gateway_fee_bps: 0 means no gateway fee — you are the gateway. pooled_mining_only pauses work if the pool link ever drops, rather than serving stale jobs.

5 · Point your ASICs at your gateway

On each miner (Goldshell, Antminer, etc.), set the pool to your gateway, not to xorpool.com:

The part after the dot is the worker name you’ll see in stats; the part before it can be anything with the config above (your address is credited from pool_address).

Check it’s working: your gateway’s status page is on the box at http://127.0.0.1:8000/ (reach it over an SSH tunnel: ssh -L 8000:127.0.0.1:8000 you@your-box), and within a couple of minutes of your first share your address appears in the payout window at xorpool.com/datum/miner/<your address>.

6 · Keep it running

• Both services restart on their own and come back after a reboot (systemctl enable did that).
• After the first sync, drop dbcache in bitcoin.conf to 400 and sudo systemctl restart knotsd if the box is short on RAM.
• Logs: journalctl -u knotsd -f and journalctl -u ratum-gateway -f.
• Upgrades: when a new Knots or ratum release lands, repeat step 2 or 4 and restart the service. Watch Telegram for consensus-relevant releases.

7 · If something’s off

• Gateway says no work / waiting for node — the node isn’t at the tip yet, or the template doesn’t list the fork rule. Check: sudo -u knots bitcoin-cli -datadir=/var/lib/knots getblocktemplate '{"rules":["segwit","blake2b"]}' | grep -A6 rules must include !blake2b.
• Node stuck with no peers — confirm the two addnode lines and that outbound traffic is allowed; sudo -u knots bitcoin-cli -datadir=/var/lib/knots getconnectioncount should be > 0.
• Shares rejected: BadUsername — pool_address (or an ASIC username, if you use pool_pass_full_users) is not a valid address on this chain. Typos like bc1g… for bc1q… do exactly this.
• RPC timeouts in the gateway log on a small VPS — usually the node validating a fresh block; harmless if occasional. If constant, give the node more RAM/dbcache or fewer maxconnections.
• ASICs can’t connect — something between them and the gateway blocks port 23334 (a firewall on the machine or at the provider). Test with nc -vz YOUR-GATEWAY-IP 23334 from the miners’ network.

Still stuck? Ask in Telegram — happy to walk through it with you.