docs: document optional fallback daemons in the env examples

Records the fallback list as an OPTION rather than an expectation, with the
caveat that matters here: a fallback only helps if it can fail independently.
A second daemon in the same office shares the outage that takes the first one
down. A node reachable over a separate path — a home node across the mesh, or a
public/community node — is what actually adds availability.

Also records the split the operator identified: free/credits instances only need
the daemon for block height, so a remote node is a reasonable fallback there.
Instances taking payments should prefer daemons they control, because block
height feeds match fairness and entropy. Either way each endpoint still has to
pass the chain-identity check, so a remote node cannot serve another chain.

src/.env.example

@@ -377,6 +377,32 @@ PRIMARY_WALLET_ENDPOINT=http://127.0.0.1:34570
 PRIMARY_RPC_ENDPOINT=http://127.0.0.1:34568
 FALLBACK_RPC_ENDPOINT=http://127.0.0.1:34568
 
+# OPTIONAL: additional daemons, comma or whitespace separated, in PREFERENCE ORDER.
+# PRIMARY/FALLBACK above are appended to this list and the whole thing is deduplicated —
+# note that the two defaults are the SAME host, so out of the box there is exactly one node
+# and no redundancy at all.
+#
+# A fallback only helps if it can fail independently. A second daemon in the same rack (or the
+# same office) shares the outage that takes the first one down, so it buys nothing; a node
+# reachable over a separate path — a home node across the mesh, or a public/community node — is
+# what actually adds availability.
+#
+# Every endpoint must still pass the chain-identity check before it may answer, so listing a
+# remote node cannot silently serve a different chain's data. For FREE / CREDITS instances the
+# daemon is only supplying block height, so a remote node is a reasonable fallback. For instances
+# taking PAYMENTS, prefer daemons you control: block height feeds match fairness and entropy, and
+# an untrusted node is an untrusted input to those.
+#
+# RPC_ENDPOINTS=http://127.0.0.1:34568,http://10.42.1.40:34568
+#
+# How long to stay on a backup before re-testing the preferred node (ms, minimum 1000).
+# RPC_PREFERRED_RETRY_MS=60000
+#
+# When NO endpoint answers, the server does not guess: entries are refused with a clear message
+# and nothing is charged. There is intentionally no wallet failover — two wallet-rpc processes
+# over one wallet file can spend the same outputs — so a wallet outage declines paid intake while
+# credits and free play keep working.
+
 # How often to poll for new blocks (milliseconds)
 RPC_POLL_INTERVAL=2000
 

src/.env.mainnet.example

@@ -78,6 +78,32 @@ WALLET_RPC_USER=wownerogue
 WALLET_RPC_PASSWORD=CHANGE_ME_STRONG_RPC_PASSWORD
 PRIMARY_RPC_ENDPOINT=http://127.0.0.1:34568
 FALLBACK_RPC_ENDPOINT=http://127.0.0.1:34568
+
+# OPTIONAL: additional daemons, comma or whitespace separated, in PREFERENCE ORDER.
+# PRIMARY/FALLBACK above are appended to this list and the whole thing is deduplicated —
+# note that the two defaults are the SAME host, so out of the box there is exactly one node
+# and no redundancy at all.
+#
+# A fallback only helps if it can fail independently. A second daemon in the same rack (or the
+# same office) shares the outage that takes the first one down, so it buys nothing; a node
+# reachable over a separate path — a home node across the mesh, or a public/community node — is
+# what actually adds availability.
+#
+# Every endpoint must still pass the chain-identity check before it may answer, so listing a
+# remote node cannot silently serve a different chain's data. For FREE / CREDITS instances the
+# daemon is only supplying block height, so a remote node is a reasonable fallback. For instances
+# taking PAYMENTS, prefer daemons you control: block height feeds match fairness and entropy, and
+# an untrusted node is an untrusted input to those.
+#
+# RPC_ENDPOINTS=http://127.0.0.1:34568,http://10.42.1.40:34568
+#
+# How long to stay on a backup before re-testing the preferred node (ms, minimum 1000).
+# RPC_PREFERRED_RETRY_MS=60000
+#
+# When NO endpoint answers, the server does not guess: entries are refused with a clear message
+# and nothing is charged. There is intentionally no wallet failover — two wallet-rpc processes
+# over one wallet file can spend the same outputs — so a wallet outage declines paid intake while
+# credits and free play keep working.
 RPC_POLL_INTERVAL=2000
 
 DIFFICULTY_PRESET=normal