Running a Node

A node (cheshire-aggregator node) follows Bitcoin and the share chain, works out each round’s batch and jobs, and builds and sends the same settlement as every other node. With contribute on, it also proves jobs and is paid in notes (paying the provers). A prover is just a node with contribute on.

This is for developers and operators. It is a research prototype; expect rough edges.

What you need

• A machine with Rust (each crate pins its own toolchain) and about 10 GB of free memory if it proves (a tree job ~4 GB, the final job ~10 GB, estimates). A tree job takes about 6–7 minutes on a recent Mac.
• A Bitcoin node running GSR: bitcoin-gsr/bitcoin branch gsr at de567461, with 0xc2 switched on. For gsr-net, the repository builds and runs one for you (scripts/gsr-net.sh).
• The repository, bootstrapped (building from source).

The steps, in outline

# 1. build
CHESHIRE_BOOTSTRAP_GSR=1 scripts/bootstrap.sh
(cd aggregator && cargo build --release)
bash scripts/gen-merged-fixed.sh        # the verifier's merged table, ~6 min, no proving

# 2. a gsr-net node (30-second blocks; kept apart from any other signet build)
scripts/gsr-net.sh build
scripts/gsr-net.sh ensure               # config, sync, checks 0xc2 is active

# 3. the share-chain node
CHESHIRE_BLOCK_SECS=30 \
CHESHIRE_SHARE_PEERS=<peer url>,<peer url> \
  aggregator/target/release/cheshire-aggregator node 19500

# 4. prove when idle
aggregator/target/release/cheshire-aggregator contribute on --node http://127.0.0.1:19500
aggregator/target/release/cheshire-aggregator earnings --node http://127.0.0.1:19500

Each node keeps its own store of the pool (its record, trees and rounds). It is seeded from the pool’s genesis record or synced from the chain (cheshire-aggregator sync-chain).

Settings that matter

variable	what
CHESHIRE_BLOCK_SECS	the chain’s block spacing: 30 on gsr-net. Every node of a pool must agree; it is part of the share chain’s genesis
CHESHIRE_SHARE_PEERS	other nodes to gossip with
CHESHIRE_SHARE_BIND	the API’s address (default 127.0.0.1); off loopback it needs CHESHIRE_SHARE_ADMIN_TOKEN
CHESHIRE_SHARE_CONTRIBUTE=1	prove from the start (CHESHIRE_SHARE_IDLE_ONLY=0: also while you use the computer)
CHESHIRE_SHARE_THREADS, CHESHIRE_SHARE_MAX_MEM_GB	caps for proving
CHESHIRE_SHARE_MERGE=1	also run the deposit-merging service, paid from this node’s wallet
CHESHIRE_SHARE_FANOUT	fan out confirmed vaults from this node’s wallet (on by default)
CHESHIRE_SHARE_ONION	this node’s .onion address, served to wallets in GET /peers

The full list is at the top of aggregator/src/sharecli.rs and aggregator/src/main.rs.

Your pay

Your node’s prover seed lives in its data directory. Back it up. Pay arrives as notes six settlements after the work, under one-time pay keys derived from that seed. cheshire-aggregator prover-wallet rebuilds the pay notes from the seed and the chain alone, and withdraw spends them.

A public node

To serve phones, put the node behind a TLS proxy with an operator token, and, ideally, an onion address so phones reach it with no Tor exit in between. The repository’s hosting kit (infra/hosting/: systemd units, a Caddy config, a torrc example) and docs/gsr-net-hosting.md walk through it. Open routes are rate-limited; the operator routes (/contribute, and the operator’s fields of /status and /earnings) need the token.

Checks

• cheshire-aggregator check-supply: the solvency check, no proving.
• GET /status, GET /round, GET /chain: the node’s view of Bitcoin and the share chain.