Automatic relay discovery over Nostr + call-to-action

Relay operators announce their relay with -announcerelay=host:port; every node
discovers announced relays (kind 38502) and adds them to its failover list, so
volunteer relays join with no maintainer edit or approval. Anti-spam cap +
validation; relays are trustless (echan makes a bad relay unable to read/MITM).
README: automatic relay-volunteer guide, 'don't let the network die' section.

6 files changed, 170 insertions, 18 deletions

diff --git a/README.md b/README.md
index 5f1c2bb..d5be586 100644
--- a/README.md
+++ b/README.md
@@ -49,6 +49,24 @@ promise back.
 
 ---
 
+<div align="center">
+
+## 🔥 Don't let the network die — run a node
+
+A cryptocurrency is only as alive as the people running it. Every node that mines,
+relays, and stays online makes Bitflash **faster, freer, and impossible to shut down.**
+No companies. No servers to trust. No gatekeepers — just people, one CPU each.
+
+### Download it. Run it. Keep it alive.
+
+**[⬇️ Windows](../../releases/latest)** &nbsp;·&nbsp; **[🐧 Linux](#-linux-node--miner)** &nbsp;·&nbsp; **[🛰️ Run a relay](#-become-a-relay-volunteer--automatically)**
+
+*The network needs you online. Close this tab and it's one node weaker.*
+
+</div>
+
+---
+
 ## ✨ Features
 
 | | |
@@ -138,31 +156,33 @@ source, then the `bitflash-node` binary. Debian/Ubuntu.
 Built with **MSYS2 UCRT64** (g++ 16, wxWidgets 3.2, OpenSSL 3, Berkeley DB). See
 [`build.sh`](build.sh) and `src/makefile.mingw`.
 
-### 🛰️ Become a relay volunteer
+### 🛰️ Become a relay volunteer — automatically
 
 Relays are the meeting points that let nodes behind CGNAT find each other. More
-relays, spread across more places, make the network **faster** and **harder to
-knock offline**. If you have a VPS or box with a public IP, you can run one and
-directly strengthen Bitflash:
+relays, in more places, make the network **faster** and **harder to knock
+offline**. If you have a VPS with a public IP, you can add one — and **the whole
+network discovers it automatically. No approval, no gatekeeper, no waiting.**
 
 **1. Run the relay — one command:**
 ```bash
 sudo bash relay/install-bitflash-relay.sh 8434
 ```
-It builds a tiny, dependency-free daemon, applies basic anti-flood firewall
-rules, and installs it as a `systemd` service (auto-restarts, survives reboot).
+Builds a tiny, dependency-free daemon, applies anti-flood firewall rules, and
+installs it as a `systemd` service (auto-restarts, survives reboot).
 
 **2. Open TCP port `8434`** in your firewall / cloud panel.
 
-**3. Get it into the network.** Send your relay's `IP:8434` by
-[opening an issue](../../issues) (or a pull request adding it to the seed list
-in `src/nostr.cpp`). A maintainer reviews it and includes it in the **seed list**
-of the next release — then every node starts using it automatically, with
-failover if any relay goes down.
+**3. Announce it** by running a node that advertises your relay:
+```bash
+./bitflash-node -gen -announcerelay=YOUR_PUBLIC_IP:8434
+```
+That node publishes your relay over Nostr; every other node discovers it within
+a minute and adds it to its failover list. **Done — you're part of the backbone.**
 
-> 🔒 A relay **never sees your traffic** — it only forwards end-to-end-encrypted
-> bytes and pairs peers by their `.btf` key. It holds no keys and reads nothing.
-> A 1 GB VPS is plenty, and every relay you add makes the whole network tougher.
+> 🔒 A relay is **trustless** — it only forwards end-to-end-encrypted bytes and
+> pairs peers by their `.btf` key. It **cannot read, tamper with, or MITM** your
+> traffic; a malicious relay can at most refuse to forward, and nodes simply fail
+> over. That's exactly why anyone can run one safely. A 1 GB VPS is plenty.
 
 <details>
 <summary>Run the Linux node 24/7 (systemd)</summary>
@@ -214,7 +234,7 @@ systemctl daemon-reload && systemctl enable --now bitflash-node
 - [x] Headless Linux node/miner
 - [x] Fair-launch, stable-parameter relaunch
 - [x] Redundant relays across regions with automatic failover
-- [ ] Automatic relay discovery over Nostr (self-announcing volunteer relays)
+- [x] Automatic relay discovery over Nostr (self-announcing volunteer relays)
 - [ ] Optional direct IPv6 transport (opt-in, for public backbone nodes)
 - [ ] One-click installers
 
diff --git a/src/headless.cpp b/src/headless.cpp
index 646476f..cdb8ac9 100644
--- a/src/headless.cpp
+++ b/src/headless.cpp
@@ -80,6 +80,7 @@ int main(int argc, char* argv[])
             "  -datadir=<dir>        data directory (default ~/.bitflash)\n"
             "  -port=<n>             P2P listen port (default 8433)\n"
             "  -rvrelay=host:port    rendezvous meeting relay (has a seed default)\n"
+            "  -announcerelay=h:p    announce a relay you run so nodes discover it\n"
             "  -connectbtf=<a>.btf   keep a connection to a specific .btf peer\n"
             "  -solomine             mine without waiting for a peer (testing)\n"
             "  -debug                verbose logging\n",
@@ -96,6 +97,8 @@ int main(int argc, char* argv[])
         addrProxy = CAddress(mapArgs["/proxy"].c_str());
     if (mapArgs.count("/rvrelay"))
         vBtfMeetingRelays = { mapArgs["/rvrelay"] };
+    if (mapArgs.count("/announcerelay"))
+        strBtfAnnounceRelay = mapArgs["/announcerelay"];
     if (mapArgs.count("/connectbtf"))
         strBtfConnect = mapArgs["/connectbtf"];
     if (mapArgs.count("/debug"))
diff --git a/src/net.cpp b/src/net.cpp
index 659de05..31afaf5 100644
--- a/src/net.cpp
+++ b/src/net.cpp
@@ -442,18 +442,27 @@ void ThreadBtfAccept(void* parg)
         Sleep(5000);
     }
     size_t iRelay = 0;
+    bool fPicked = false;
     loop
     {
         if (fShutdown)
             return;
-        if (vBtfMeetingRelays.empty())
+        // Curated seeds + relays discovered from Nostr announcements.
+        vector<string> relays = BtfAllRelays();
+        if (relays.empty())
         {
             Sleep(10000); // no meeting relay configured
             continue;
         }
+        // Random start spreads nodes across all relays (incl. volunteer ones).
+        if (!fPicked)
+        {
+            iRelay = (size_t)GetRand(relays.size());
+            fPicked = true;
+        }
         // Stick to the current relay while it works; on failure, fail over to
-        // the next seed so a DDoS'd/blocked relay IP can't keep us offline.
-        string strMeeting = vBtfMeetingRelays[iRelay % vBtfMeetingRelays.size()];
+        // the next one so a DDoS'd/blocked relay IP can't keep us offline.
+        string strMeeting = relays[iRelay % relays.size()];
         size_t colon = strMeeting.rfind(':');
         if (colon == string::npos)
         {
diff --git a/src/nostr.cpp b/src/nostr.cpp
index 59817f5..44aec56 100644
--- a/src/nostr.cpp
+++ b/src/nostr.cpp
@@ -31,6 +31,13 @@ static const int   BTF_DESC_KIND = 38501;
 // the abandoned test .btf descriptors lingering on the relays become invisible.
 static const char* BTF_DESC_DTAG = "btf-descriptor-2";
 
+// Relay auto-discovery: a relay operator announces their relay as an addressable
+// event (kind 38502) so every node learns it automatically -- no manual
+// seed-list edit, no maintainer approval. Volunteer relays just work.
+static const int    BTF_RELAY_KIND = 38502;
+static const char*  BTF_RELAY_DTAG = "btf-relay-2";
+static const size_t BTF_MAX_DISCOVERED_RELAYS = 50; // anti-spam cap
+
 // Nostr network/scope for Bitflash. Events are replaceable (NIP-78).
 static const int   NOSTR_KIND   = 30078;
 static const char* NOSTR_DTAG   = "bitflash-mainnet-2";
@@ -82,6 +89,48 @@ void BtfSetActiveRelay(const string& relay)
         strBtfActiveRelay = relay;
 }
 
+// A relay this node advertises on Nostr for others to discover (/announcerelay).
+string strBtfAnnounceRelay;
+// Relays learned from other operators' Nostr announcements.
+static set<string> g_discoveredRelays;
+static CCriticalSection cs_discoveredRelays;
+
+// Basic sanity: "host:port" with a numeric 1..65535 port and a plausible host.
+static bool LooksLikeRelay(const string& r)
+{
+    size_t colon = r.rfind(':');
+    if (colon == string::npos || colon == 0 || colon + 1 >= r.size())
+        return false;
+    if (r.size() > 100)
+        return false;
+    for (size_t i = colon + 1; i < r.size(); i++)
+        if (!isdigit((unsigned char)r[i]))
+            return false;
+    int port = atoi(r.c_str() + colon + 1);
+    if (port <= 0 || port > 65535)
+        return false;
+    // host: allow letters, digits, dot, dash, colon (IPv6 not supported yet)
+    for (size_t i = 0; i < colon; i++)
+    {
+        char c = r[i];
+        if (!(isalnum((unsigned char)c) || c == '.' || c == '-'))
+            return false;
+    }
+    return true;
+}
+
+// Every relay to try: curated seeds first (reliable bootstrap), then the ones
+// discovered from Nostr announcements (volunteer relays).
+vector<string> BtfAllRelays()
+{
+    vector<string> all = vBtfMeetingRelays;
+    CRITICAL_BLOCK(cs_discoveredRelays)
+        foreach(const string& r, g_discoveredRelays)
+            if (find(all.begin(), all.end(), r) == all.end())
+                all.push_back(r);
+    return all;
+}
+
 
 //
 // Utilities
@@ -560,6 +609,21 @@ static void PublishDescriptor(CWebSocket& ws, CNostrKey& key)
     }
 }
 
+// Announce our relay (from /announcerelay=host:port) so every node discovers it
+// automatically -- volunteer relays join the network with no maintainer step.
+static void PublishRelayAnnouncement(CWebSocket& ws, CNostrKey& key)
+{
+    if (strBtfAnnounceRelay.empty())
+        return;
+    json tags = json::array({ json::array({ "d", BTF_RELAY_DTAG }) });
+    json ev;
+    if (BuildSignedEvent(key, BTF_RELAY_KIND, tags, strBtfAnnounceRelay, ev))
+    {
+        json pub = json::array({ "EVENT", ev });
+        ws.SendText(pub.dump());
+    }
+}
+
 // Resolve a `.btf` address via a relay: fetch the descriptor published by that
 // address's key and verify it self-certifies under the decoded pubkey.
 static bool ResolveDescriptor(CWebSocket& ws, void* ctx, const string& btfAddr,
@@ -654,6 +718,9 @@ static bool SeedFromRelay(CNostrKey& key, const string& relay)
     // Publish our self-certifying .btf descriptor (rendezvous discovery)
     PublishDescriptor(ws, key);
 
+    // If we run a relay, announce it so others discover it automatically
+    PublishRelayAnnouncement(ws, key);
+
     // Subscribe to receive the announcements of other nodes
     json filter = json::object();
     filter["kinds"] = json::array({ NOSTR_KIND });
@@ -736,6 +803,49 @@ static bool SeedFromRelay(CNostrKey& key, const string& relay)
             }
         }
     }
+
+    // Discover volunteer relays announced by other operators (kind 38502). Nodes
+    // add these to their failover list automatically, so anyone can strengthen
+    // the network without a maintainer editing the seed list. Bad/dead relays
+    // just fail to pair and get skipped -- and a relay is trustless anyway (it
+    // only forwards echan ciphertext and can't read or MITM the traffic).
+    ws.SendText(json::array({ "CLOSE", "btf-disc" }).dump());
+    {
+        json rfilter = json::object();
+        rfilter["kinds"] = json::array({ BTF_RELAY_KIND });
+        rfilter["#d"]    = json::array({ BTF_RELAY_DTAG });
+        rfilter["limit"] = 200;
+        json rreq = json::array({ "REQ", "btf-relays", rfilter });
+        if (ws.SendText(rreq.dump()))
+        {
+            for (;;)
+            {
+                string msg;
+                if (!ws.RecvText(msg))
+                    break;
+                json j;
+                try { j = json::parse(msg); } catch (...) { continue; }
+                if (!j.is_array() || j.empty()) continue;
+                string type = j[0].get<string>();
+                if (type == "EVENT" && j.size() >= 3)
+                {
+                    const json& ev = j[2];
+                    if (!ev.contains("content") || !ev.contains("kind")) continue;
+                    if (ev["kind"].get<int>() != BTF_RELAY_KIND) continue;
+                    string r = ev["content"].get<string>();
+                    if (!LooksLikeRelay(r)) continue;
+                    bool fNew = false;
+                    CRITICAL_BLOCK(cs_discoveredRelays)
+                        if (g_discoveredRelays.size() < BTF_MAX_DISCOVERED_RELAYS)
+                            fNew = g_discoveredRelays.insert(r).second;
+                    if (fNew)
+                        printf("Nostr: discovered relay %s\n", r.c_str());
+                }
+                else if (type == "EOSE")
+                    break;
+            }
+        }
+    }
     return true;
 }
 
diff --git a/src/nostr.h b/src/nostr.h
index 41e59df..b878db9 100644
--- a/src/nostr.h
+++ b/src/nostr.h
@@ -32,6 +32,12 @@ std::string BtfActiveRelay();
 // Record the relay this node just registered its service at (thread-safe).
 void BtfSetActiveRelay(const std::string& relay);
 
+// If set (via /announcerelay=host:port), this node announces that relay on
+// Nostr so other nodes discover it automatically -- no manual seed-list edit.
+extern std::string strBtfAnnounceRelay;
+// Every relay to try: curated seeds + relays discovered from Nostr announcements.
+std::vector<std::string> BtfAllRelays();
+
 // Copy this node's .btf identity (lazily loading or generating it): the x-only
 // pubkey (= the .btf address) and the x25519 secret for the end-to-end channel.
 bool BtfGetIdentity(unsigned char pubkey[32], unsigned char enc_sk[32]);
diff --git a/src/ui.cpp b/src/ui.cpp
index cb1a94d..311a78e 100644
--- a/src/ui.cpp
+++ b/src/ui.cpp
@@ -2974,6 +2974,10 @@ bool CMyApp::OnInit2()
     if (mapArgs.count("/rvrelay"))
         vBtfMeetingRelays = { mapArgs["/rvrelay"] };
 
+    // Announce a relay you run so other nodes discover it automatically.
+    if (mapArgs.count("/announcerelay"))
+        strBtfAnnounceRelay = mapArgs["/announcerelay"];
+
     // Keep an anonymous outbound connection to a specific .btf peer.
     if (mapArgs.count("/connectbtf"))
         strBtfConnect = mapArgs["/connectbtf"];