From b291bd3c1380ec602fd059c512ae681e5ab024b8 Mon Sep 17 00:00:00 2001 From: jwinterm Date: Sun, 26 Jul 2026 08:00:00 -0400 Subject: [PATCH] docs: document optional fallback daemons in the env examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 26 ++++++++++++++++++++++++++ src/.env.mainnet.example | 26 ++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/src/.env.example b/src/.env.example index 97d0ee8..7e3d9d8 100644 --- a/src/.env.example +++ b/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 diff --git a/src/.env.mainnet.example b/src/.env.mainnet.example index b56d933..6794b46 100644 --- a/src/.env.mainnet.example +++ b/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