How NanoFarmer works
How NanoFarmer works
XCHPool NanoFarmer · Technical details
What runs on your computer, what XCHPool runs, which messages travel between them, and what protects your keys and your rewards. Written for farmers who want to know the details.
Chia 2.7.4 farmer and harvester
Pooling protocol v1, plot NFTs
What a full node does, and what NanoFarmer changes
Farming Chia takes three programs that work together. The official Chia app runs all three on your computer. NanoFarmer keeps two of them on your computer and lets XCHPool run the third.
Harvester
Reads your plots. For every signage point it applies the plot filter, which lets only a small share of the plots through (on mainnet currently 1 in 256), and looks up proofs of space in the plots that pass.
Farmer
Sends each signage point to the harvester and receives its proofs. A proof that meets your pool difficulty becomes a partial for the pool; a proof good enough to win a block goes to the full node. With the harvester it signs partials and blocks.
Full node
Keeps a copy of the whole blockchain (well over 100 GB) and stays in sync with the network. It delivers a new signage point about every 9.4 seconds and builds and broadcasts the block when your proof wins.
NanoFarmer runs Chia's own farmer and harvester on your computer, unchanged, and replaces the full node with one connection to XCHPool. XCHPool's full nodes deliver the signage points and build the block when you win. Nothing to download or sync, and your keys stay with you.
Your computer, with the whole blockchain
XCHPool's full nodes, through the gateway
Not included: import your words into Sage or the Chia wallet to see your rewards
The components
What each part does, where it runs and what it is built with.
NanoFarmer app
It can start when you log in: a per-user entry on Windows, a LaunchAgent on macOS, a systemd user service on Linux. No administrator rights. On Windows, an icon in the notification area opens the window again after it was closed, and quits NanoFarmer.
One program per system. It runs as a background agent that supervises the engine, runs the uplink, serves the local interface and installs updates.
The window is a native window on macOS and an app window of Edge or Chrome (or your default browser) on Windows and Linux. Closing it does not stop farming.
A command line with the same functions, so NanoFarmer also runs without a screen over SSH, for example on a Raspberry Pi.
Uplink
When the connection drops it reconnects by itself, with a pause that grows from 1 to 30 seconds.
A stand-in full node on 127.0.0.1. Chia's farmer connects to it exactly as it would to a real full node, over TLS 1.3 with the engine's own certificate.
It copies Chia's messages byte for byte into one WebSocket to the gateway. Only a few text messages of the gateway's own (a greeting, warnings, statistics) are extra; they never reach the farmer, and warnings show up in the app.
Its signing guard checks the few messages that matter for your rewards (see Keys and trust).
Gateway
Only forwards proofs from plot NFTs that farm to XCHPool. It limits connections per internet address and in total, and tells the app why when it refuses one.
Part of the NanoFarmer server, built on Chia 2.7.4's own networking code. To your farmer it is a full node; to XCHPool's full nodes it is a farmer.
Sends every new signage point once to every connected NanoFarmer, and the latest one right after you connect.
Checks every declared proof exactly before a full node sees it: a real signage point, a plot NFT plot, a valid proof that really wins, matching signatures, no repeat.
NanoFarmer server
A REST service at https://pool.xchpool.org, made for the app. A browser only reads its public release files and update manifests, as the NanoFarmer page does for its downloads.
Finds your plot NFTs, prepares pool-paid creation and joining, and serves the releases and the signed update manifests.
Pays for new plot NFTs and join fees from a funding wallet of its own, apart from the pool's own wallets.
Pool
The same XCHPool every member farms with, over the standard pooling protocol v1.
Your farmer registers itself and sends its partials straight to the pool, not through the gateway. Points and payouts work as for every other member.
Chain API
XCHPool's public blockchain API, a service apart from the NanoFarmer server.
The app uses it to find a plot NFT's coin on the blockchain before it trusts it, and, before a join from self-pooling, to check for rewards still waiting at the plot NFT.
Explorer and My Farm
"Open My Farm" in the app logs you in with your plot NFT's pool login link.
Each NanoFarmer install is a harvester of its own on My Farm. Shortly after the pool accepted its first partial, the app names it after the device (brand, model and system; never your computer's name or your user name). You can rename it in the app or on My Farm.
The partial response times card shows how fast each harvester answers.
From signage point to partial or block
What happens about every 9.4 seconds, with the message names Chia uses.
A new signage point
XCHPool's full nodes send each signage point to the gateway, which passes it once to every connected NanoFarmer.
Checked and handed on
The uplink checks that the signage point's hashes match the data sent with it, then hands it to the farmer.
Plot filter and lookup
The harvester applies the plot filter, looks up proofs in the plots that pass and returns every proof it finds.
Partial to the pool
A proof that meets your pool difficulty becomes a partial. The harvester signs it with the plot key, the farmer adds its own signature and sends it straight to the pool over HTTPS. The pool checks it, awards points and records the response time.
Declared
A proof good enough for a block is declared. The uplink requires your own reward address in it and asks for the data behind the hashes it will be asked to sign. The gateway checks the proof and that it really wins, then passes it to the full nodes. A proof that does not win would make a full node drop the gateway's connection, which is why the gateway checks so strictly.
Signed
The full node builds the block and asks for its signatures. The uplink only lets that request through when the block pays the farmer reward to your address. The harvester signs, and the signatures go back the same way.
Broadcast
The full node finishes the block and broadcasts it. The farmer reward (0.125 XCH plus the block's fees) goes to your reward address; the pool's share goes to your plot NFT's pool address, where XCHPool collects it.
Keys and trust
Your keys stay on your computer. Here is what that means in practice, what NanoFarmer will and will not sign, and what the XCHPool side can and cannot do.
Where your key lives
Settings can show the words again so you can write them on paper: only after you confirm, with the passphrase when one is set, without a copy button, and hidden again after a minute.
NanoFarmer creates a new 24-word key or imports yours and keeps it in its own Chia keyring, in its own data folder, never in the official Chia app's key folder.
The farmer reads its farmer, pool login and plot NFT owner keys from that keyring. The words never leave your computer and are never written to a log.
An optional passphrase (at least 8 characters) encrypts the keyring. NanoFarmer keeps it in your system's credential store so farming starts by itself; where there is none, it asks for the passphrase after every start.
What NanoFarmer signs, and what it refuses
Pool values: the pool URL, the pool's target address, the lock height and the delay time are built into the app. It refuses to create, join or sign anything that differs, whatever a server says.
Plot NFT spends: the helper rebuilds every spend the server proposes from Chia's own puzzle code, checks it against the pool values built into the app, and only then signs. It never signs a hash it cannot rebuild.
Blocks: Chia's farmer signs block hashes without seeing what they stand for, and the full node takes the farmer reward address from an unsigned field. So the uplink's signing guard only passes a signing request when the block data behind it comes along, matches the hashes and pays the farmer reward to the address NanoFarmer set up.
Signage points: the plot key that signs signage points also signs blocks. The guard only passes signage points whose hashes are the hashes of their own source data, which can never be block data, and no more than a few times the chain's own rate.
What the XCHPool side can and cannot do
Chia's consensus rules send the pool's share of every block to your plot NFT's pool address, as with any pool.
The gateway and XCHPool's full nodes could withhold or break a block you win, as any full node you rely on could. They cannot make NanoFarmer sign a block that pays your farmer reward to someone else.
Made-up signage points (Chia's farmer protocol carries no proof of time) would only cost your harvester some lookups, which the guard caps, and never produce a signature that fits a block.
What the app sends
To the explorer: your harvester's name, made from the device's brand, model and system.
To the gateway: Chia's farmer messages (your proofs and signatures), plus the app and engine version, your type of system and a random install ID.
To the pool: your partials and your farm's registration, as every Chia farmer does.
To the NanoFarmer server: public keys to find and create your plot NFT, and the plot NFT you join. Never a private key and never your words.
The local interface
The window and the command line talk to the app on 127.0.0.1 only, with a random token that is new at every start, strict host and origin checks and a strict content security policy, so web pages cannot use it.
Plot NFT: creating and joining
NanoFarmer farms plot NFT plots with pooling protocol v1. In step 2 of the app it looks for plot NFTs under the first 20 owner keys of your key, then uses, joins or creates one.
A plot NFT that farms to XCHPool
It is used as it is, once the app has checked on the blockchain that it belongs to your key.
One join spend. Rewards still waiting at the plot NFT are claimed to you first.
A plot NFT at another pool
Two spends: leave now, and join once the other pool's lock height has passed. You sign both at once; the server sends the second when it is due.
A new plot NFT is created for you. It is ready after 3 confirmations, usually within a few minutes.
The pool pays the 1 mojo and the fee
The pool's coin pays 1 mojo to your own address, and your key turns that mojo into the plot NFT's launcher in the same transaction. So the plot NFT is yours from the start: the Chia wallet finds it, and you can leave XCHPool with standard tools.
Free creation is limited to once per internet address per 24 hours and once per key.
The app writes the plot NFT into the engine's pool settings; the farmer then registers with the pool by itself.
The server prepares the spends; the helper rebuilds each one with Chia's own code and signs only when it ends at XCHPool with your own owner key.
The app calls a join done only once the blockchain shows it, whatever the server reports.
A join that could only go through more than about a day from now (a long lock height at the old pool) is refused before anything is signed. The pool-paid join fee has limits of its own; beyond them a join still goes through, without the pool's fee.
Pool values built into the app
100 blocks, about half an hour: the wait when a plot NFT leaves XCHPool
7 days (604,800 seconds): rewards the pool does not collect in that time can be claimed back to your address
Updates and release security
App and engine update separately. A new engine is downloaded while you farm and switched in when no plot NFT job is running; if it does not start, the previous engine comes back. A new app version is used from the next start of the app, or right away when you update from the app.
The app checks for updates at start and every 6 hours, against a manifest signed with an Ed25519 key. Two public keys are built in, so the signing key can be replaced.
The manifest names every file with its size and SHA-256, expires after a while, can set a minimum version, and never takes the app or the engine back to an older version.
Two channels, stable and beta. A new version can reach a share of installs first, chosen by a hash of the random install ID.
The previous version of each stays on disk for a rollback.
The signing key is kept offline on one machine, never on a server or in the build pipeline.
The checksum file of every release is signed too, for first downloads, and the NanoFarmer page shows the SHA-256 of each file.
The programs are not code-signed with Apple or Microsoft certificates yet, so your system asks you to confirm the first start.
The engine holds your keyring and updates without a click, so a single build machine must not be enough to ship one. Every engine release is built twice from a tagged commit, in two separate clean build environments. The build is reproducible, and the signing tool refuses to sign unless both builds produced byte-for-byte identical bundles.
Platforms and requirements
Installer (per user) or portable zip
macOS 15 or newer, Apple silicon
Linux x86-64, glibc 2.28 or newer
Linux ARM64, glibc 2.28 or newer (Raspberry Pi 4 and 5 with a 64-bit system)
tar.gz with install script and systemd user service
Disk
About 1 GB free for the app, the engine, the previous version of each and the logs. No blockchain.
Network
Local ports
The engine uses its own ports next to Chia's defaults: daemon 55410, farmer 8457, uplink 8454, farmer RPC 8569, harvester RPC 8570. When one is taken, the whole set moves up by 100.
Timing and response times
Chia farming runs on a clock. These are the numbers that matter.
Partials do not travel through the gateway. Only the signage point comes from XCHPool's full nodes through the gateway to you; the farmer sends the partial straight to the pool.
64 signage points in every 10-minute sub-slot
Chia's harvester warns when looking up a plot takes longer
from the signage point to the block's infusion: the proof, the block and its signatures must be ready before that
the time the gateway gives your farmer to return a block's signatures
The pool measures every partial's response time: from the moment the signage point reached the pool to the moment your partial arrived. A partial that arrives after the pool's time limit is refused as too late and earns nothing.
My Farm shows your response times per harvester: the median, the 95th percentile and your margin to the limit, with the limit drawn as a red dashed line. For a NanoFarmer farm the time includes the relay through the gateway; the usual causes of slow answers are slow or sleeping disks, plots on network storage and a busy computer.
What NanoFarmer does not do
No full node: it does not download, store or sync the blockchain.
No wallet: to see or send your rewards, import your words into Sage or the Chia wallet.
No OG plots: plots made with a pool public key (-p) are skipped, and the app lists them so you know which ones.
No plotting: the app explains the plotters and fills in the command, but does not make plots itself.
No other pools for now: it farms plot NFTs at XCHPool only.
No plots above C7, and no Gigahorse compressed, NoSSD or DrPlotter plots: Chia 2.7.4 cannot farm them.
No Proof of Space 2 plots yet: those need Chia 3.0, which the engine can move to as an update of its own.
No port forwarding: every connection goes out from your computer.
Design choices
A WebSocket instead of Chia's peer port
No new farming protocol
The WebSocket carries Chia's own farmer-protocol messages byte for byte. The farmer is stock Chia and cannot tell it is not talking to a real full node.
Key maths only in Chia's code
Chia derives its keys in its own way, and another library could get them wrong without anyone noticing. So every Chia key derivation and signature is made by Chia's own code in the engine; the Go app does none.
App and engine apart
The Go app stays small, and the engine can move to a new Chia version on its own schedule, such as Chia 3.0 before the Proof of Space 2 fork.
Questions and answers
Can XCHPool redirect my block reward?
Not the farmer reward: NanoFarmer only signs a block that pays it to your address. The pool's share goes to your plot NFT's pool address by Chia's rules, as with any pool. What the XCHPool side could do is hold back a block you win, as any full node you rely on could.
What happens when my internet connection drops?
The uplink reconnects by itself, with a pause that grows from 1 to 30 seconds, and Chia's farmer reconnects to the uplink. If the connection drops between a winning proof and the signing request, the gateway sends the request to your new connection.
Can I run NanoFarmer on several computers with one key?
Yes. Every install makes its own harvester certificates, so each computer shows up as a harvester of its own on My Farm, with its own name.
Can I leave XCHPool?
Yes. The plot NFT is yours, and the Chia wallet can move it to another pool or to self-pooling. XCHPool's lock height is 100 blocks, about half an hour.
Why does the app not send partials through the gateway?
It does not have to. Partials use the standard pooling protocol over HTTPS, exactly as for a farmer with a full node. Only the full node's part is moved to XCHPool.