From 35981f56488d31b694cecdd9fdb980f6be300884 Mon Sep 17 00:00:00 2001
From: Nic-dorman <nbdorman@gmail.com>
Date: Mon, 20 Apr 2026 18:23:45 +0100
Subject: [PATCH 1/6] feat: populate BootstrapManager cache from client peer
 interactions

The quote, chunk PUT, and chunk GET paths now feed a shared helper
that upserts peers on success via add_discovered_peer and records
latency/success on both outcomes via update_peer_metrics. Cold-start
clients can now load real, quality-scored peers from the persisted
bootstrap cache instead of always restarting from the 7 bundled
peers. Failures never insert, so unreachable peers don't consume
cache quota.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ant-core/src/data/client/chunk.rs     | 28 ++++++--
 ant-core/src/data/client/mod.rs       | 32 +++++++++
 ant-core/src/data/client/quote.rs     | 11 ++-
 ant-core/tests/e2e_bootstrap_cache.rs | 99 +++++++++++++++++++++++++++
 4 files changed, 162 insertions(+), 8 deletions(-)
 create mode 100644 ant-core/tests/e2e_bootstrap_cache.rs

diff --git a/ant-core/src/data/client/chunk.rs b/ant-core/src/data/client/chunk.rs
index 592e6a0..02949b8 100644
--- a/ant-core/src/data/client/chunk.rs
+++ b/ant-core/src/data/client/chunk.rs
@@ -3,7 +3,7 @@
 //! Chunks are immutable, content-addressed data blocks where the address
 //! is the BLAKE3 hash of the content.
 
-use crate::data::client::Client;
+use crate::data::client::{record_peer_outcome, Client};
 use crate::data::error::{Error, Result};
 use ant_node::ant_protocol::{
     ChunkGetRequest, ChunkGetResponse, ChunkMessage, ChunkMessageBody, ChunkPutRequest,
@@ -15,7 +15,7 @@ use ant_node::CLOSE_GROUP_MAJORITY;
 use bytes::Bytes;
 use futures::stream::{FuturesUnordered, StreamExt};
 use std::future::Future;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 use tracing::{debug, warn};
 
 /// Data type identifier for chunks (used in quote requests).
@@ -171,7 +171,8 @@ impl Client {
         let addr_hex = hex::encode(address);
         let timeout_secs = self.config().store_timeout_secs;
 
-        send_and_await_chunk_response(
+        let start = Instant::now();
+        let result = send_and_await_chunk_response(
             node,
             target_peer,
             message_bytes,
@@ -204,7 +205,14 @@ impl Client {
                 ))
             },
         )
-        .await
+        .await;
+
+        let reachable = !matches!(&result, Err(Error::Network(_) | Error::Timeout(_)));
+        let rtt_ms =
+            reachable.then(|| u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX));
+        record_peer_outcome(node, *target_peer, peer_addrs, reachable, rtt_ms).await;
+
+        result
     }
 
     /// Retrieve a chunk from the Autonomi network.
@@ -278,7 +286,8 @@ impl Client {
         let addr_hex = hex::encode(address);
         let timeout_secs = self.config().store_timeout_secs;
 
-        send_and_await_chunk_response(
+        let start = Instant::now();
+        let result = send_and_await_chunk_response(
             node,
             peer,
             message_bytes,
@@ -325,7 +334,14 @@ impl Client {
                 ))
             },
         )
-        .await
+        .await;
+
+        let reachable = !matches!(&result, Err(Error::Network(_) | Error::Timeout(_)));
+        let rtt_ms =
+            reachable.then(|| u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX));
+        record_peer_outcome(node, *peer, peer_addrs, reachable, rtt_ms).await;
+
+        result
     }
 
     /// Check if a chunk exists on the network.
diff --git a/ant-core/src/data/client/mod.rs b/ant-core/src/data/client/mod.rs
index ccce50d..9f30418 100644
--- a/ant-core/src/data/client/mod.rs
+++ b/ant-core/src/data/client/mod.rs
@@ -244,3 +244,35 @@ impl Client {
         Ok(peers)
     }
 }
+
+/// Feed a peer contact outcome into the `BootstrapManager` cache so future
+/// cold-starts can rank peers by observed latency and success rate.
+///
+/// On success, upserts the peer (subject to saorsa-core Sybil checks:
+/// rate limiting + IP diversity) and records the RTT. On failure, only
+/// updates the quality score of peers already in the cache — we never
+/// insert peers we couldn't reach.
+///
+/// Errors from both upstream calls are swallowed: peer-cache bookkeeping
+/// must never abort a user operation.
+pub(crate) async fn record_peer_outcome(
+    node: &Arc<P2PNode>,
+    peer_id: PeerId,
+    addrs: &[MultiAddr],
+    success: bool,
+    rtt_ms: Option<u64>,
+) {
+    if success {
+        let before = node.cached_peer_count().await;
+        let _ = node.add_discovered_peer(peer_id, addrs.to_vec()).await;
+        let after = node.cached_peer_count().await;
+        if after > before {
+            debug!("Bootstrap cache grew: {before} -> {after} peers");
+        }
+    }
+    if let Some(primary) = addrs.iter().find(|a| a.socket_addr().is_some()) {
+        let _ = node
+            .update_peer_metrics(primary, success, rtt_ms, None)
+            .await;
+    }
+}
diff --git a/ant-core/src/data/client/quote.rs b/ant-core/src/data/client/quote.rs
index 3e13626..c2d7978 100644
--- a/ant-core/src/data/client/quote.rs
+++ b/ant-core/src/data/client/quote.rs
@@ -3,7 +3,7 @@
 //! Handles requesting storage quotes from network nodes and
 //! managing payment for data storage.
 
-use crate::data::client::Client;
+use crate::data::client::{record_peer_outcome, Client};
 use crate::data::error::{Error, Result};
 use ant_node::ant_protocol::{
     ChunkMessage, ChunkMessageBody, ChunkQuoteRequest, ChunkQuoteResponse,
@@ -14,7 +14,7 @@ use ant_node::{CLOSE_GROUP_MAJORITY, CLOSE_GROUP_SIZE};
 use evmlib::common::Amount;
 use evmlib::PaymentQuote;
 use futures::stream::{FuturesUnordered, StreamExt};
-use std::time::Duration;
+use std::time::{Duration, Instant};
 use tracing::{debug, warn};
 
 /// Compute XOR distance between a peer's ID bytes and a target address.
@@ -106,6 +106,7 @@ impl Client {
             let node_clone = node.clone();
 
             let quote_future = async move {
+                let start = Instant::now();
                 let result = send_and_await_chunk_response(
                     &node_clone,
                     &peer_id_clone,
@@ -147,6 +148,12 @@ impl Client {
                 )
                 .await;
 
+                let reachable = !matches!(&result, Err(Error::Network(_) | Error::Timeout(_)));
+                let rtt_ms = reachable
+                    .then(|| u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX));
+                record_peer_outcome(&node_clone, peer_id_clone, &addrs_clone, reachable, rtt_ms)
+                    .await;
+
                 (peer_id_clone, addrs_clone, result)
             };
 
diff --git a/ant-core/tests/e2e_bootstrap_cache.rs b/ant-core/tests/e2e_bootstrap_cache.rs
new file mode 100644
index 0000000..1321db8
--- /dev/null
+++ b/ant-core/tests/e2e_bootstrap_cache.rs
@@ -0,0 +1,99 @@
+//! E2E tests for BootstrapManager cache population from real peer interactions (V2-202).
+//!
+//! Proves that client-side uploads and downloads feed the BootstrapManager
+//! cache via `add_discovered_peer` + `update_peer_metrics`, so that subsequent
+//! cold-starts can load quality-scored peers beyond the bundled bootstrap set.
+//!
+//! ## Why the assertion is "cache grew", not "cache >= 10"
+//!
+//! saorsa-core's `JoinRateLimiterConfig` defaults (`max_joins_per_24_per_hour: 3`)
+//! cap new-peer inserts at 3 per /24 subnet per hour for Sybil protection.
+//! Every testnet node binds to `127.0.0.1`, so all 11 available peers live in
+//! one /24 — the rate limiter permits only the first 3 to join the cache in
+//! a single run. In production, peers are spread across many /24s (typically
+//! one per ASN), so `min_peers_to_save = 10` is easily crossed.
+//!
+//! Asserting `after > before` is sufficient proof here: it confirms the client
+//! library correctly wires `add_discovered_peer` and `update_peer_metrics`
+//! into upload and download paths. The threshold-crossing behavior is an
+//! upstream (saorsa-core + saorsa-transport) contract we trust and cover via
+//! manual verification against a live, multi-subnet testnet.
+
+#![allow(clippy::unwrap_used, clippy::expect_used)]
+
+mod support;
+
+use ant_core::data::{Client, ClientConfig};
+use bytes::Bytes;
+use serial_test::serial;
+use std::sync::Arc;
+use support::MiniTestnet;
+
+const BOOTSTRAP_CACHE_TEST_NODES: usize = 12;
+
+#[tokio::test(flavor = "multi_thread")]
+#[serial]
+async fn test_bootstrap_cache_fills_from_upload() {
+    let testnet = MiniTestnet::start(BOOTSTRAP_CACHE_TEST_NODES).await;
+    let node = testnet.node(3).expect("Node 3 should exist");
+
+    let client = Client::from_node(Arc::clone(&node), ClientConfig::default())
+        .with_wallet(testnet.wallet().clone());
+
+    let before = node.cached_peer_count().await;
+
+    let content = Bytes::from("v2-202 bootstrap cache e2e payload");
+    client
+        .chunk_put(content)
+        .await
+        .expect("chunk_put should succeed with payment");
+
+    let after = node.cached_peer_count().await;
+
+    assert!(
+        after > before,
+        "cache should grow after peer interactions: before={before} after={after}"
+    );
+
+    drop(client);
+    testnet.teardown().await;
+}
+
+#[tokio::test(flavor = "multi_thread")]
+#[serial]
+async fn test_bootstrap_cache_fills_from_download() {
+    let testnet = MiniTestnet::start(BOOTSTRAP_CACHE_TEST_NODES).await;
+    let node = testnet.node(3).expect("Node 3 should exist");
+
+    let client = Client::from_node(Arc::clone(&node), ClientConfig::default())
+        .with_wallet(testnet.wallet().clone());
+
+    // Put a chunk first so there's something to download.
+    let content = Bytes::from("v2-202 download path payload");
+    let addr = client
+        .chunk_put(content.clone())
+        .await
+        .expect("chunk_put should succeed");
+
+    let before_download = node.cached_peer_count().await;
+
+    let retrieved = client
+        .chunk_get(&addr)
+        .await
+        .expect("chunk_get should succeed");
+    assert!(retrieved.is_some(), "chunk should be retrievable");
+
+    let after_download = node.cached_peer_count().await;
+
+    // Download path must also feed the cache. Rate limiter is already saturated
+    // by the upload above (same /24), so we can only assert that the download
+    // at minimum did not *shrink* the cache and that quality-score updates on
+    // existing peers ran without error.
+    assert!(
+        after_download >= before_download,
+        "cache must not shrink after download: before={before_download} after={after_download}"
+    );
+
+    drop(client);
+    testnet.teardown().await;
+}

From 6315fb90800ca8019d23309d9a6dffc2950d086b Mon Sep 17 00:00:00 2001
From: Nic-dorman <nbdorman@gmail.com>
Date: Tue, 21 Apr 2026 09:18:51 +0100
Subject: [PATCH 2/6] refactor: address review feedback on bootstrap cache
 hooks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Blockers:
- Plumb explicit `success: bool` from each call site's `Ok` branch instead
  of inferring from error variants. Previously `Err::Protocol`, `::Payment`,
  `::Serialization`, `::InvalidData`, and remote PutResponse::Error all
  fired `add_discovered_peer` + wrote an RTT — the opposite of the stated
  "failures never insert" invariant.
- Drop RTT on the PUT path. `chunk_put_with_proof` wraps a ~4 MB payload
  upload, so the wall-clock was dominated by the uploader's uplink rather
  than the peer's responsiveness. Quote-path and GET-path RTTs still
  feed quality scoring.
- Add a cold-start-from-disk test that populates a BootstrapManager
  (via `add_peer_trusted` to skip the /24 rate limiter), saves, drops,
  reopens against the same cache_dir, and asserts peers reload. Closes
  the loop on the cold-start value prop.

Polish:
- Prefer globally-routable socket addresses when picking a peer's cache
  key. Previously a peer advertising `[10.0.0.5, 203.0.113.1]` would be
  keyed under the RFC1918 address and metrics recorded over the public
  address would land on a stale entry.
- Fold the weak "after_download >= before_download" assertion into the
  main test (now performs PUT + GET + asserts cache grew). The /24 rate
  limiter saturates during the PUT, so a standalone download assertion
  carries no information.

Nits:
- Use `as u64` for elapsed millis (saturates only after ~584M years).
- Move `record_peer_outcome` out of `client/mod.rs` into its own
  `client/peer_cache.rs` module.
- Doc now notes that both upstream calls silently discard errors.

Test comment on the 3-peer ceiling is rewritten to describe both Sybil
mechanisms accurately: `BootstrapIpLimiter` (IP diversity, exempted for
loopback) and `JoinRateLimiter` (temporal, NOT exempted) — the latter
is what caps /24 inserts at 3/hour.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Cargo.lock                             |   1 +
 ant-core/Cargo.toml                    |   5 +
 ant-core/src/data/client/chunk.rs      |  20 ++--
 ant-core/src/data/client/mod.rs        |  33 +-----
 ant-core/src/data/client/peer_cache.rs | 126 +++++++++++++++++++++
 ant-core/src/data/client/quote.rs      |  10 +-
 ant-core/tests/e2e_bootstrap_cache.rs  | 148 ++++++++++++++++---------
 7 files changed, 244 insertions(+), 99 deletions(-)
 create mode 100644 ant-core/src/data/client/peer_cache.rs

diff --git a/Cargo.lock b/Cargo.lock
index eb3ed33..cf86812 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -869,6 +869,7 @@ dependencies = [
  "rand 0.8.6",
  "reqwest 0.12.28",
  "rmp-serde",
+ "saorsa-core",
  "saorsa-pqc 0.5.1",
  "self-replace",
  "self_encryption",
diff --git a/ant-core/Cargo.toml b/ant-core/Cargo.toml
index e15abd7..dc910b8 100644
--- a/ant-core/Cargo.toml
+++ b/ant-core/Cargo.toml
@@ -57,6 +57,11 @@ serial_test = "3"
 anyhow = "1"
 alloy = { version = "1.6", features = ["node-bindings"] }
 tokio-test = "0.4"
+# Direct access to BootstrapManager used by the cold-start-from-disk test,
+# which populates a cache via `add_peer_trusted` (bypasses Sybil rate limits)
+# and then verifies reload after save. Version tracks ant-node's transitive
+# saorsa-core dep.
+saorsa-core = "0.23"
 
 [[example]]
 name = "start-local-devnet"
diff --git a/ant-core/src/data/client/chunk.rs b/ant-core/src/data/client/chunk.rs
index 02949b8..46174e1 100644
--- a/ant-core/src/data/client/chunk.rs
+++ b/ant-core/src/data/client/chunk.rs
@@ -3,7 +3,8 @@
 //! Chunks are immutable, content-addressed data blocks where the address
 //! is the BLAKE3 hash of the content.
 
-use crate::data::client::{record_peer_outcome, Client};
+use crate::data::client::peer_cache::record_peer_outcome;
+use crate::data::client::Client;
 use crate::data::error::{Error, Result};
 use ant_node::ant_protocol::{
     ChunkGetRequest, ChunkGetResponse, ChunkMessage, ChunkMessageBody, ChunkPutRequest,
@@ -171,7 +172,6 @@ impl Client {
         let addr_hex = hex::encode(address);
         let timeout_secs = self.config().store_timeout_secs;
 
-        let start = Instant::now();
         let result = send_and_await_chunk_response(
             node,
             target_peer,
@@ -207,10 +207,11 @@ impl Client {
         )
         .await;
 
-        let reachable = !matches!(&result, Err(Error::Network(_) | Error::Timeout(_)));
-        let rtt_ms =
-            reachable.then(|| u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX));
-        record_peer_outcome(node, *target_peer, peer_addrs, reachable, rtt_ms).await;
+        // No RTT recorded on the PUT path: the wall-clock is dominated by
+        // the ~4 MB payload upload, which reflects the uploader's uplink
+        // rather than the peer's responsiveness. Quote-path and GET-path
+        // RTTs still feed quality scoring.
+        record_peer_outcome(node, *target_peer, peer_addrs, result.is_ok(), None).await;
 
         result
     }
@@ -336,10 +337,9 @@ impl Client {
         )
         .await;
 
-        let reachable = !matches!(&result, Err(Error::Network(_) | Error::Timeout(_)));
-        let rtt_ms =
-            reachable.then(|| u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX));
-        record_peer_outcome(node, *peer, peer_addrs, reachable, rtt_ms).await;
+        let success = result.is_ok();
+        let rtt_ms = success.then(|| start.elapsed().as_millis() as u64);
+        record_peer_outcome(node, *peer, peer_addrs, success, rtt_ms).await;
 
         result
     }
diff --git a/ant-core/src/data/client/mod.rs b/ant-core/src/data/client/mod.rs
index 9f30418..5f0b67d 100644
--- a/ant-core/src/data/client/mod.rs
+++ b/ant-core/src/data/client/mod.rs
@@ -10,6 +10,7 @@ pub mod data;
 pub mod file;
 pub mod merkle;
 pub mod payment;
+pub(crate) mod peer_cache;
 pub mod quote;
 
 use crate::data::client::cache::ChunkCache;
@@ -244,35 +245,3 @@ impl Client {
         Ok(peers)
     }
 }
-
-/// Feed a peer contact outcome into the `BootstrapManager` cache so future
-/// cold-starts can rank peers by observed latency and success rate.
-///
-/// On success, upserts the peer (subject to saorsa-core Sybil checks:
-/// rate limiting + IP diversity) and records the RTT. On failure, only
-/// updates the quality score of peers already in the cache — we never
-/// insert peers we couldn't reach.
-///
-/// Errors from both upstream calls are swallowed: peer-cache bookkeeping
-/// must never abort a user operation.
-pub(crate) async fn record_peer_outcome(
-    node: &Arc<P2PNode>,
-    peer_id: PeerId,
-    addrs: &[MultiAddr],
-    success: bool,
-    rtt_ms: Option<u64>,
-) {
-    if success {
-        let before = node.cached_peer_count().await;
-        let _ = node.add_discovered_peer(peer_id, addrs.to_vec()).await;
-        let after = node.cached_peer_count().await;
-        if after > before {
-            debug!("Bootstrap cache grew: {before} -> {after} peers");
-        }
-    }
-    if let Some(primary) = addrs.iter().find(|a| a.socket_addr().is_some()) {
-        let _ = node
-            .update_peer_metrics(primary, success, rtt_ms, None)
-            .await;
-    }
-}
diff --git a/ant-core/src/data/client/peer_cache.rs b/ant-core/src/data/client/peer_cache.rs
new file mode 100644
index 0000000..7b30f15
--- /dev/null
+++ b/ant-core/src/data/client/peer_cache.rs
@@ -0,0 +1,126 @@
+//! Bootstrap-cache population helpers.
+//!
+//! Wires client-side peer contacts into saorsa-core's `BootstrapManager`
+//! so the persistent cache reflects real peer quality across sessions.
+
+use ant_node::core::{MultiAddr, P2PNode, PeerId};
+use std::net::{IpAddr, SocketAddr};
+use std::sync::Arc;
+use tracing::debug;
+
+/// Feed a peer contact outcome into the `BootstrapManager` cache so future
+/// cold-starts can rank peers by observed latency and success.
+///
+/// `success = true`: upserts the peer via `add_discovered_peer` (subject to
+/// saorsa-core Sybil checks — rate limit + IP diversity) and records RTT via
+/// `update_peer_metrics`.
+///
+/// `success = false`: only updates the quality score of peers already in
+/// the cache. Unreachable peers are never inserted.
+///
+/// Both upstream calls silently discard errors — peer-cache bookkeeping
+/// must never abort a user operation. Enable the `saorsa_core::bootstrap`
+/// tracing target to see rejection reasons.
+pub(crate) async fn record_peer_outcome(
+    node: &Arc<P2PNode>,
+    peer_id: PeerId,
+    addrs: &[MultiAddr],
+    success: bool,
+    rtt_ms: Option<u64>,
+) {
+    if success {
+        let before = node.cached_peer_count().await;
+        let _ = node.add_discovered_peer(peer_id, addrs.to_vec()).await;
+        let after = node.cached_peer_count().await;
+        if after > before {
+            debug!("Bootstrap cache grew: {before} -> {after} peers");
+        }
+    }
+    if let Some(primary) = select_primary_multiaddr(addrs) {
+        let _ = node
+            .update_peer_metrics(primary, success, rtt_ms, None)
+            .await;
+    }
+}
+
+/// Pick the `MultiAddr` to use as the peer's cache key.
+///
+/// Prefers a globally routable socket address over RFC1918 / link-local /
+/// loopback. Without this, a peer advertising `[10.0.0.5, 203.0.113.1]`
+/// would be keyed under the RFC1918 address, so metrics recorded during
+/// a contact over the public address would land on a stale cache entry.
+/// Falls back to any socket-addressable `MultiAddr` if none look global.
+fn select_primary_multiaddr(addrs: &[MultiAddr]) -> Option<&MultiAddr> {
+    addrs
+        .iter()
+        .find(|a| a.socket_addr().is_some_and(|sa| is_globally_routable(&sa)))
+        .or_else(|| addrs.iter().find(|a| a.socket_addr().is_some()))
+}
+
+fn is_globally_routable(addr: &SocketAddr) -> bool {
+    match addr.ip() {
+        IpAddr::V4(v4) => {
+            !v4.is_private()
+                && !v4.is_loopback()
+                && !v4.is_link_local()
+                && !v4.is_broadcast()
+                && !v4.is_documentation()
+                && !v4.is_unspecified()
+        }
+        IpAddr::V6(v6) => {
+            // Full Ipv6Addr::is_global is unstable; this is the practical
+            // subset that mirrors the IPv4 checks above.
+            !v6.is_loopback()
+                && !v6.is_unspecified()
+                && !v6.is_multicast()
+                && !v6.segments()[0].eq(&0xfe80) // link-local fe80::/10 (approx)
+                && !matches!(v6.segments()[0] & 0xfe00, 0xfc00) // unique-local fc00::/7
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::net::{Ipv4Addr, Ipv6Addr};
+
+    #[test]
+    fn globally_routable_v4() {
+        assert!(is_globally_routable(&SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1)),
+            80
+        )));
+        assert!(!is_globally_routable(&SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(10, 0, 0, 5)),
+            80
+        )));
+        assert!(!is_globally_routable(&SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::LOCALHOST),
+            80
+        )));
+        assert!(!is_globally_routable(&SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1)),
+            80
+        )));
+    }
+
+    #[test]
+    fn globally_routable_v6() {
+        assert!(is_globally_routable(&SocketAddr::new(
+            IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1)),
+            80
+        )));
+        assert!(!is_globally_routable(&SocketAddr::new(
+            IpAddr::V6(Ipv6Addr::LOCALHOST),
+            80
+        )));
+        assert!(!is_globally_routable(&SocketAddr::new(
+            IpAddr::V6(Ipv6Addr::new(0xfe80, 0, 0, 0, 0, 0, 0, 1)),
+            80
+        )));
+        assert!(!is_globally_routable(&SocketAddr::new(
+            IpAddr::V6(Ipv6Addr::new(0xfc00, 0, 0, 0, 0, 0, 0, 1)),
+            80
+        )));
+    }
+}
diff --git a/ant-core/src/data/client/quote.rs b/ant-core/src/data/client/quote.rs
index c2d7978..4523e91 100644
--- a/ant-core/src/data/client/quote.rs
+++ b/ant-core/src/data/client/quote.rs
@@ -3,7 +3,8 @@
 //! Handles requesting storage quotes from network nodes and
 //! managing payment for data storage.
 
-use crate::data::client::{record_peer_outcome, Client};
+use crate::data::client::peer_cache::record_peer_outcome;
+use crate::data::client::Client;
 use crate::data::error::{Error, Result};
 use ant_node::ant_protocol::{
     ChunkMessage, ChunkMessageBody, ChunkQuoteRequest, ChunkQuoteResponse,
@@ -148,10 +149,9 @@ impl Client {
                 )
                 .await;
 
-                let reachable = !matches!(&result, Err(Error::Network(_) | Error::Timeout(_)));
-                let rtt_ms = reachable
-                    .then(|| u64::try_from(start.elapsed().as_millis()).unwrap_or(u64::MAX));
-                record_peer_outcome(&node_clone, peer_id_clone, &addrs_clone, reachable, rtt_ms)
+                let success = result.is_ok();
+                let rtt_ms = success.then(|| start.elapsed().as_millis() as u64);
+                record_peer_outcome(&node_clone, peer_id_clone, &addrs_clone, success, rtt_ms)
                     .await;
 
                 (peer_id_clone, addrs_clone, result)
diff --git a/ant-core/tests/e2e_bootstrap_cache.rs b/ant-core/tests/e2e_bootstrap_cache.rs
index 1321db8..80303ef 100644
--- a/ant-core/tests/e2e_bootstrap_cache.rs
+++ b/ant-core/tests/e2e_bootstrap_cache.rs
@@ -1,4 +1,4 @@
-//! E2E tests for BootstrapManager cache population from real peer interactions (V2-202).
+//! E2E tests for BootstrapManager cache population from real peer interactions.
 //!
 //! Proves that client-side uploads and downloads feed the BootstrapManager
 //! cache via `add_discovered_peer` + `update_peer_metrics`, so that subsequent
@@ -6,18 +6,27 @@
 //!
 //! ## Why the assertion is "cache grew", not "cache >= 10"
 //!
-//! saorsa-core's `JoinRateLimiterConfig` defaults (`max_joins_per_24_per_hour: 3`)
-//! cap new-peer inserts at 3 per /24 subnet per hour for Sybil protection.
-//! Every testnet node binds to `127.0.0.1`, so all 11 available peers live in
-//! one /24 — the rate limiter permits only the first 3 to join the cache in
-//! a single run. In production, peers are spread across many /24s (typically
-//! one per ASN), so `min_peers_to_save = 10` is easily crossed.
+//! saorsa-core gates `add_peer` through two independent Sybil mechanisms:
 //!
-//! Asserting `after > before` is sufficient proof here: it confirms the client
-//! library correctly wires `add_discovered_peer` and `update_peer_metrics`
-//! into upload and download paths. The threshold-crossing behavior is an
-//! upstream (saorsa-core + saorsa-transport) contract we trust and cover via
-//! manual verification against a live, multi-subnet testnet.
+//! 1. `BootstrapIpLimiter::can_accept` — the IP-diversity limiter. When the
+//!    node is built with `allow_loopback = true` (as `MiniTestnet` does),
+//!    this returns early for loopback IPs, so it is NOT the bottleneck here.
+//! 2. `JoinRateLimiter::check_join_allowed` — the temporal rate limiter.
+//!    Defaults cap inserts at 3 per /24 subnet per hour and are NOT exempt
+//!    for loopback (`saorsa-core/src/rate_limit.rs:254` has no `is_loopback`
+//!    branch). All testnet nodes bind to `127.0.0.1`, so all ~11 available
+//!    peers fall in the single `127.0.0.0/24` bucket — the first 3 land in
+//!    the cache, the rest are rejected with `Subnet24LimitExceeded`.
+//!
+//! In production, peers span many /24s (typically one per ASN), so the /24
+//! rate limit is never the binding constraint and crossing
+//! `min_peers_to_save = 10` is straightforward.
+//!
+//! Asserting `after > before` is sufficient proof that the client library
+//! correctly wires `add_discovered_peer` and `update_peer_metrics` into the
+//! upload (and, transitively, download) paths. The threshold-crossing +
+//! persistence behavior is an upstream contract covered by saorsa-transport's
+//! own tests.
 
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 
@@ -33,7 +42,7 @@ const BOOTSTRAP_CACHE_TEST_NODES: usize = 12;
 
 #[tokio::test(flavor = "multi_thread")]
 #[serial]
-async fn test_bootstrap_cache_fills_from_upload() {
+async fn test_bootstrap_cache_grows_after_client_activity() {
     let testnet = MiniTestnet::start(BOOTSTRAP_CACHE_TEST_NODES).await;
     let node = testnet.node(3).expect("Node 3 should exist");
 
@@ -42,14 +51,25 @@ async fn test_bootstrap_cache_fills_from_upload() {
 
     let before = node.cached_peer_count().await;
 
-    let content = Bytes::from("v2-202 bootstrap cache e2e payload");
-    client
-        .chunk_put(content)
+    let content = Bytes::from("bootstrap-cache e2e payload");
+    let address = client
+        .chunk_put(content.clone())
         .await
         .expect("chunk_put should succeed with payment");
 
-    let after = node.cached_peer_count().await;
+    // The GET exercises the download-side hook (chunk_get_from_peer), which
+    // would silently break if record_peer_outcome's signature drifted from
+    // what chunk.rs expects. The assertion here is just that the round-trip
+    // works — cache growth from the GET itself is capped by the /24 rate
+    // limiter which saturated during the PUT.
+    let retrieved = client
+        .chunk_get(&address)
+        .await
+        .expect("chunk_get should succeed")
+        .expect("chunk should be retrievable");
+    assert_eq!(retrieved.content.as_ref(), content.as_ref());
 
+    let after = node.cached_peer_count().await;
     assert!(
         after > before,
         "cache should grow after peer interactions: before={before} after={after}"
@@ -59,41 +79,65 @@ async fn test_bootstrap_cache_fills_from_upload() {
     testnet.teardown().await;
 }
 
-#[tokio::test(flavor = "multi_thread")]
-#[serial]
-async fn test_bootstrap_cache_fills_from_download() {
-    let testnet = MiniTestnet::start(BOOTSTRAP_CACHE_TEST_NODES).await;
-    let node = testnet.node(3).expect("Node 3 should exist");
-
-    let client = Client::from_node(Arc::clone(&node), ClientConfig::default())
-        .with_wallet(testnet.wallet().clone());
-
-    // Put a chunk first so there's something to download.
-    let content = Bytes::from("v2-202 download path payload");
-    let addr = client
-        .chunk_put(content.clone())
-        .await
-        .expect("chunk_put should succeed");
-
-    let before_download = node.cached_peer_count().await;
-
-    let retrieved = client
-        .chunk_get(&addr)
+/// Cold-start-from-disk round-trip.
+///
+/// ## What this proves
+///
+/// - A populated `BootstrapManager` cache with ≥ `min_peers_to_save` peers
+///   is persisted to disk on `save()`.
+/// - A *fresh* `BootstrapManager` constructed against the same `cache_dir`
+///   reloads the persisted peers on startup.
+///
+/// Together with `test_bootstrap_cache_grows_after_client_activity` above
+/// (which exercises the add-during-activity hook), this closes the loop on
+/// the V2-202 value prop: cold-start clients reload real peers from disk.
+///
+/// ## Why `add_peer_trusted` and not `add_discovered_peer`
+///
+/// `add_discovered_peer` goes through `BootstrapManager::add_peer`, which
+/// runs both the IP-diversity limiter and the temporal `JoinRateLimiter`.
+/// The latter caps inserts at 3 per /24 subnet per hour and has no
+/// loopback exemption. A real test that populates 15 peers through that
+/// path would need peers on distinct /24s — not practical on a single-host
+/// testnet. `add_peer_trusted` skips both limiters and talks to the same
+/// underlying `BootstrapCache::add_seed` that our hooks ultimately feed,
+/// so the persistence path exercised is identical to production's.
+#[tokio::test]
+async fn test_bootstrap_cache_roundtrip_through_disk() {
+    use saorsa_core::{BootstrapConfig, BootstrapManager};
+    use std::net::{IpAddr, Ipv4Addr, SocketAddr};
+
+    let cache_dir = tempfile::TempDir::new().expect("create temp cache dir");
+    let config = BootstrapConfig {
+        cache_dir: cache_dir.path().to_path_buf(),
+        ..BootstrapConfig::default()
+    };
+
+    // Populate with peers on distinct /24s (cosmetic — add_peer_trusted
+    // skips rate limits — but keeps the data realistic if saorsa-transport
+    // ever tightens its invariants).
+    let peer_count = 15;
+    {
+        let mgr = BootstrapManager::with_config(config.clone())
+            .await
+            .expect("construct populating BootstrapManager");
+        for i in 0..peer_count {
+            let addr = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, i as u8 + 1)), 9000);
+            mgr.add_peer_trusted(&addr, vec![addr]).await;
+        }
+        assert_eq!(mgr.peer_count().await, peer_count, "in-memory populate");
+        mgr.save()
+            .await
+            .expect("save should succeed above threshold");
+    }
+
+    // Fresh manager, same cache_dir: peers should be reloaded.
+    let reloaded = BootstrapManager::with_config(config)
         .await
-        .expect("chunk_get should succeed");
-    assert!(retrieved.is_some(), "chunk should be retrievable");
-
-    let after_download = node.cached_peer_count().await;
-
-    // Download path must also feed the cache. Rate limiter is already saturated
-    // by the upload above (same /24), so we can only assert that the download
-    // at minimum did not *shrink* the cache and that quality-score updates on
-    // existing peers ran without error.
-    assert!(
-        after_download >= before_download,
-        "cache must not shrink after download: before={before_download} after={after_download}"
+        .expect("construct reloading BootstrapManager");
+    let reloaded_count = reloaded.peer_count().await;
+    assert_eq!(
+        reloaded_count, peer_count,
+        "all {peer_count} peers should reload from disk, got {reloaded_count}"
     );
-
-    drop(client);
-    testnet.teardown().await;
 }

From dd0884038d1ae9346806b368a3d3b8137c3076df Mon Sep 17 00:00:00 2001
From: Nic-dorman <nbdorman@gmail.com>
Date: Tue, 21 Apr 2026 09:49:16 +0100
Subject: [PATCH 3/6] fix(test): use truly public IPs in peer_cache unit tests

`203.0.113.0/24` (TEST-NET-3) and `2001:db8::/32` are documentation
prefixes that `is_documentation()` / my v6 approximation correctly
reject. The previous test asserted the opposite on those ranges, which
passed locally on Windows but failed on Linux/macOS CI. Use
`8.8.8.8` and `2606:4700:4700::1111` instead, and add an assertion that
the TEST-NET-3 range IS rejected (that's the behaviour we actually want).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ant-core/src/data/client/peer_cache.rs | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/ant-core/src/data/client/peer_cache.rs b/ant-core/src/data/client/peer_cache.rs
index 7b30f15..dc67aa0 100644
--- a/ant-core/src/data/client/peer_cache.rs
+++ b/ant-core/src/data/client/peer_cache.rs
@@ -86,8 +86,9 @@ mod tests {
 
     #[test]
     fn globally_routable_v4() {
+        // 8.8.8.8 (Google DNS) — genuinely public, not in any reserved range.
         assert!(is_globally_routable(&SocketAddr::new(
-            IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1)),
+            IpAddr::V4(Ipv4Addr::new(8, 8, 8, 8)),
             80
         )));
         assert!(!is_globally_routable(&SocketAddr::new(
@@ -102,12 +103,22 @@ mod tests {
             IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1)),
             80
         )));
+        // 203.0.113.0/24 is TEST-NET-3 documentation — rejected by
+        // `is_documentation()`, which is the behaviour we want: quality
+        // metrics should not land on addresses that are never dialed in
+        // production by spec.
+        assert!(!is_globally_routable(&SocketAddr::new(
+            IpAddr::V4(Ipv4Addr::new(203, 0, 113, 1)),
+            80
+        )));
     }
 
     #[test]
     fn globally_routable_v6() {
+        // 2606:4700:4700::1111 (Cloudflare DNS) — a real public v6 outside
+        // the `2001:db8::/32` documentation prefix.
         assert!(is_globally_routable(&SocketAddr::new(
-            IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1)),
+            IpAddr::V6(Ipv6Addr::new(0x2606, 0x4700, 0x4700, 0, 0, 0, 0, 0x1111)),
             80
         )));
         assert!(!is_globally_routable(&SocketAddr::new(

From 2da81fca25fad787eae30ac9f31cff0d6b61a394 Mon Sep 17 00:00:00 2001
From: Nic-dorman <nbdorman@gmail.com>
Date: Wed, 15 Apr 2026 10:37:41 +0100
Subject: [PATCH 4/6] feat(external-signer): add Visibility arg to
 file_prepare_upload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an external-signer path for public uploads. When a PreparedUpload
is prepared with Visibility::Public, the serialized DataMap is bundled
into the payment batch (wave-batch or merkle) as an additional chunk.
FileUploadResult::data_map_address then carries the chunk address of
the stored DataMap, giving the uploader a single network address to
share for retrieval.

Motivation: ant-gui (the Autonomi desktop GUI) currently has to block
its Public upload option in the UI because no external-signer pathway
exists for publishing the data map — `data_map_store` internally calls
`pay_for_storage`, which hard-requires a wallet, and the chunk-storage
plumbing (`store_paid_chunks`, `chunk_put_to_close_group`,
`merkle_upload_chunks`) is pub(crate), so consumers on the
external-signer path cannot hand-roll it. Bundling the data map chunk
into the existing payment batch reuses the one-signature flow that
wave-batch and merkle already use for file chunks, which lets ant-gui
thread a `visibility` flag through its existing code path and re-enable
the Public option with no extra wallet round-trip.

- `Visibility::{Private, Public}` enum (default Private)
- `Client::file_prepare_upload_with_visibility(path, visibility)`;
  the existing `file_prepare_upload(path)` now delegates with Private
  for backward compatibility
- `PreparedUpload.data_map_address: Option<[u8; 32]>` carries the
  address between prepare and finalize
- `FileUploadResult.data_map_address` is Some for public uploads
- Both `finalize_upload` and `finalize_upload_merkle` propagate the
  field; no separate network call is needed because the data map chunk
  is stored alongside the rest of the batch
- e2e test verifies Private leaves the address unset, Public records
  it, and the recorded address matches the serialized data map

The internal-wallet path (`file_upload_with_mode`) is unchanged —
ant-cli continues to use `file_upload` followed by `data_map_store`
for its public upload flow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ant-core/Cargo.toml              |  1 +
 ant-core/src/data/client/data.rs |  1 +
 ant-core/src/data/client/file.rs | 83 ++++++++++++++++++++++++++++++--
 ant-core/src/data/mod.rs         |  2 +-
 ant-core/tests/e2e_file.rs       | 76 ++++++++++++++++++++++++++++-
 5 files changed, 158 insertions(+), 5 deletions(-)

diff --git a/ant-core/Cargo.toml b/ant-core/Cargo.toml
index e15abd7..63abe68 100644
--- a/ant-core/Cargo.toml
+++ b/ant-core/Cargo.toml
@@ -57,6 +57,7 @@ serial_test = "3"
 anyhow = "1"
 alloy = { version = "1.6", features = ["node-bindings"] }
 tokio-test = "0.4"
+rmp-serde = "1"
 
 [[example]]
 name = "start-local-devnet"
diff --git a/ant-core/src/data/client/data.rs b/ant-core/src/data/client/data.rs
index 8c588dc..2541b63 100644
--- a/ant-core/src/data/client/data.rs
+++ b/ant-core/src/data/client/data.rs
@@ -206,6 +206,7 @@ impl Client {
                 prepared_chunks,
                 payment_intent,
             },
+            data_map_address: None,
         })
     }
 
diff --git a/ant-core/src/data/client/file.rs b/ant-core/src/data/client/file.rs
index acc4c31..5dcac25 100644
--- a/ant-core/src/data/client/file.rs
+++ b/ant-core/src/data/client/file.rs
@@ -373,6 +373,23 @@ fn check_disk_space_for_spill(file_size: u64) -> Result<()> {
     Ok(())
 }
 
+/// Whether the data map is published to the network for address-based retrieval.
+///
+/// A private upload stores only the data chunks and returns the `DataMap` to
+/// the caller — only someone holding that `DataMap` can reconstruct the file.
+/// A public upload additionally stores the serialized `DataMap` as a chunk on
+/// the network, yielding a single chunk address that anyone can use to
+/// retrieve the `DataMap` (via [`Client::data_map_fetch`]) and then the file.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum Visibility {
+    /// Keep the data map local; only the holder can retrieve the file.
+    #[default]
+    Private,
+    /// Publish the data map as a network chunk so anyone with the returned
+    /// address can retrieve and decrypt the file.
+    Public,
+}
+
 /// Result of a file upload: the `DataMap` needed to retrieve the file.
 #[derive(Debug, Clone)]
 pub struct FileUploadResult {
@@ -386,6 +403,10 @@ pub struct FileUploadResult {
     pub storage_cost_atto: String,
     /// Total gas cost in wei. 0 if no on-chain transactions were made.
     pub gas_cost_wei: u128,
+    /// Chunk address of the serialized `DataMap`, set only for [`Visibility::Public`]
+    /// uploads. Share this address so others can retrieve the file without the
+    /// local `DataMap` (via [`Client::data_map_fetch`] then [`Client::file_download`]).
+    pub data_map_address: Option<[u8; 32]>,
 }
 
 /// Payment information for external signing — either wave-batch or merkle.
@@ -424,6 +445,12 @@ pub struct PreparedUpload {
     pub data_map: DataMap,
     /// Payment information — either wave-batch or merkle depending on chunk count.
     pub payment_info: ExternalPaymentInfo,
+    /// Chunk address of the serialized `DataMap` when this upload was prepared
+    /// with [`Visibility::Public`]. The address is `Some` whenever the data
+    /// map chunk has been bundled into `payment_info` for payment; it is
+    /// carried through to [`FileUploadResult::data_map_address`] after
+    /// finalization.
+    pub data_map_address: Option<[u8; 32]>,
 }
 
 /// Return type for [`spawn_file_encryption`]: chunk receiver, `DataMap` oneshot, join handle.
@@ -530,11 +557,27 @@ impl Client {
 
     /// Phase 1 of external-signer upload: encrypt file and prepare chunks.
     ///
+    /// Equivalent to [`Client::file_prepare_upload_with_visibility`] with
+    /// [`Visibility::Private`] — see that method for details.
+    pub async fn file_prepare_upload(&self, path: &Path) -> Result<PreparedUpload> {
+        self.file_prepare_upload_with_visibility(path, Visibility::Private)
+            .await
+    }
+
+    /// Phase 1 of external-signer upload with explicit [`Visibility`] control.
+    ///
     /// Requires an EVM network (for contract price queries) but NOT a wallet.
     /// Returns a [`PreparedUpload`] containing the data map, prepared chunks,
     /// and a [`PaymentIntent`] that the external signer uses to construct
     /// and submit the on-chain payment transaction.
     ///
+    /// When `visibility` is [`Visibility::Public`], the serialized `DataMap`
+    /// is bundled into the payment batch as an additional chunk and its
+    /// address is recorded on the returned [`PreparedUpload`]. After
+    /// [`Client::finalize_upload`] (or `_merkle`) succeeds, that address is
+    /// surfaced via [`FileUploadResult::data_map_address`] so the uploader
+    /// can share a single address from which anyone can retrieve the file.
+    ///
     /// **Memory note:** Encryption uses disk spilling for bounded memory, but
     /// the returned [`PreparedUpload`] holds all chunk content in memory (each
     /// [`PreparedChunk`] contains a `Bytes` with the full chunk data). This is
@@ -546,9 +589,13 @@ impl Client {
     ///
     /// Returns an error if there is insufficient disk space, the file cannot
     /// be read, encryption fails, or quote collection fails.
-    pub async fn file_prepare_upload(&self, path: &Path) -> Result<PreparedUpload> {
+    pub async fn file_prepare_upload_with_visibility(
+        &self,
+        path: &Path,
+        visibility: Visibility,
+    ) -> Result<PreparedUpload> {
         debug!(
-            "Preparing file upload for external signing: {}",
+            "Preparing file upload for external signing (visibility={visibility:?}): {}",
             path.display()
         );
 
@@ -566,12 +613,35 @@ impl Client {
         // Read each chunk from disk and collect quotes concurrently.
         // Note: all PreparedChunks accumulate in memory because the external-signer
         // protocol requires them for finalize_upload. NOT memory-bounded for large files.
-        let chunk_data: Vec<Bytes> = spill
+        let mut chunk_data: Vec<Bytes> = spill
             .addresses
             .iter()
             .map(|addr| spill.read_chunk(addr))
             .collect::<std::result::Result<Vec<_>, _>>()?;
 
+        // For public uploads, bundle the serialized DataMap as an extra chunk
+        // in the same payment batch. This lets the external signer pay for
+        // the data chunks and the DataMap chunk in one flow, and lets the
+        // finalize step return the DataMap's chunk address as the shareable
+        // retrieval address.
+        let data_map_address = match visibility {
+            Visibility::Private => None,
+            Visibility::Public => {
+                let serialized = rmp_serde::to_vec(&data_map).map_err(|e| {
+                    Error::Serialization(format!("Failed to serialize DataMap: {e}"))
+                })?;
+                let bytes = Bytes::from(serialized);
+                let address = compute_address(&bytes);
+                info!(
+                    "Public upload: bundling DataMap chunk ({} bytes) at address {}",
+                    bytes.len(),
+                    hex::encode(address)
+                );
+                chunk_data.push(bytes);
+                Some(address)
+            }
+        };
+
         let chunk_count = chunk_data.len();
 
         let payment_info = if should_use_merkle(chunk_count, PaymentMode::Auto) {
@@ -634,6 +704,7 @@ impl Client {
         Ok(PreparedUpload {
             data_map,
             payment_info,
+            data_map_address,
         })
     }
 
@@ -653,6 +724,7 @@ impl Client {
         prepared: PreparedUpload,
         tx_hash_map: &HashMap<QuoteHash, TxHash>,
     ) -> Result<FileUploadResult> {
+        let data_map_address = prepared.data_map_address;
         match prepared.payment_info {
             ExternalPaymentInfo::WaveBatch {
                 prepared_chunks,
@@ -680,6 +752,7 @@ impl Client {
                     payment_mode_used: PaymentMode::Single,
                     storage_cost_atto: "0".into(),
                     gas_cost_wei: 0,
+                    data_map_address,
                 })
             }
             ExternalPaymentInfo::Merkle { .. } => Err(Error::Payment(
@@ -706,6 +779,7 @@ impl Client {
         prepared: PreparedUpload,
         winner_pool_hash: [u8; 32],
     ) -> Result<FileUploadResult> {
+        let data_map_address = prepared.data_map_address;
         match prepared.payment_info {
             ExternalPaymentInfo::Merkle {
                 prepared_batch,
@@ -725,6 +799,7 @@ impl Client {
                     payment_mode_used: PaymentMode::Merkle,
                     storage_cost_atto: "0".into(),
                     gas_cost_wei: 0,
+                    data_map_address,
                 })
             }
             ExternalPaymentInfo::WaveBatch { .. } => Err(Error::Payment(
@@ -814,6 +889,7 @@ impl Client {
                             payment_mode_used: PaymentMode::Single,
                             storage_cost_atto: sc,
                             gas_cost_wei: gc,
+                            data_map_address: None,
                         });
                     }
                     Err(e) => return Err(e),
@@ -839,6 +915,7 @@ impl Client {
             payment_mode_used: actual_mode,
             storage_cost_atto,
             gas_cost_wei,
+            data_map_address: None,
         })
     }
 
diff --git a/ant-core/src/data/mod.rs b/ant-core/src/data/mod.rs
index 7d5c676..0c0fa8d 100644
--- a/ant-core/src/data/mod.rs
+++ b/ant-core/src/data/mod.rs
@@ -22,7 +22,7 @@ pub use ant_node::client::{compute_address, DataChunk, XorName};
 pub use client::batch::{finalize_batch_payment, PaidChunk, PaymentIntent, PreparedChunk};
 pub use client::data::DataUploadResult;
 pub use client::file::{
-    DownloadEvent, ExternalPaymentInfo, FileUploadResult, PreparedUpload, UploadEvent,
+    DownloadEvent, ExternalPaymentInfo, FileUploadResult, PreparedUpload, UploadEvent, Visibility,
 };
 pub use client::merkle::{
     finalize_merkle_batch, MerkleBatchPaymentResult, PaymentMode, PreparedMerkleBatch,
diff --git a/ant-core/tests/e2e_file.rs b/ant-core/tests/e2e_file.rs
index c7b1e03..4d61c02 100644
--- a/ant-core/tests/e2e_file.rs
+++ b/ant-core/tests/e2e_file.rs
@@ -4,7 +4,7 @@
 
 mod support;
 
-use ant_core::data::Client;
+use ant_core::data::{compute_address, Client, ExternalPaymentInfo, Visibility};
 use serial_test::serial;
 use std::io::Write;
 use std::path::PathBuf;
@@ -143,3 +143,77 @@ async fn test_file_download_bytes_written() {
     drop(client);
     testnet.teardown().await;
 }
+
+/// External-signer prepare must bundle the serialized DataMap as one extra
+/// paid chunk when `Visibility::Public` is requested, and must record the
+/// resulting chunk address on the `PreparedUpload`. Private prepare must
+/// leave that address unset.
+#[tokio::test(flavor = "multi_thread")]
+#[serial]
+async fn test_file_prepare_upload_visibility() {
+    let (client, testnet) = setup().await;
+
+    let data = vec![0x37u8; 4096];
+    let mut input_file = NamedTempFile::new().expect("create temp file");
+    input_file.write_all(&data).expect("write temp file");
+    input_file.flush().expect("flush temp file");
+
+    let private = client
+        .file_prepare_upload_with_visibility(input_file.path(), Visibility::Private)
+        .await
+        .expect("private prepare should succeed");
+
+    assert!(
+        private.data_map_address.is_none(),
+        "private uploads must not publish a DataMap address"
+    );
+
+    let public = client
+        .file_prepare_upload_with_visibility(input_file.path(), Visibility::Public)
+        .await
+        .expect("public prepare should succeed");
+
+    let public_addr = public
+        .data_map_address
+        .expect("public prepare must record the DataMap chunk address");
+
+    // The recorded address must match a fresh hash of the serialized DataMap,
+    // proving the address refers to exactly the chunk that was added to the
+    // payment batch (and that `data_map_fetch` on this address will later
+    // yield the same DataMap we're holding).
+    let expected_bytes = rmp_serde::to_vec(&public.data_map).expect("serialize DataMap");
+    let expected_addr = compute_address(&expected_bytes);
+    assert_eq!(
+        public_addr, expected_addr,
+        "data_map_address must equal compute_address(rmp_serde::to_vec(&data_map))"
+    );
+
+    // A small file produces a wave-batch payment (well under the merkle
+    // threshold), and the datamap chunk must appear in that batch.
+    match (&private.payment_info, &public.payment_info) {
+        (
+            ExternalPaymentInfo::WaveBatch {
+                prepared_chunks: priv_chunks,
+                ..
+            },
+            ExternalPaymentInfo::WaveBatch {
+                prepared_chunks: pub_chunks,
+                ..
+            },
+        ) => {
+            assert_eq!(
+                pub_chunks.len(),
+                priv_chunks.len() + 1,
+                "public prepare must add exactly one chunk (the serialized DataMap) to the batch"
+            );
+            assert!(
+                pub_chunks.iter().any(|c| c.address == public_addr),
+                "the extra chunk must be the DataMap chunk at the recorded address"
+            );
+        }
+        other => panic!("expected wave-batch for a 4KB file, got {other:?}"),
+    }
+
+    drop(client);
+    testnet.teardown().await;
+}

From 586a129c0d6cef34533c268aa72fb7d695b1bd3e Mon Sep 17 00:00:00 2001
From: Nic-dorman <nbdorman@gmail.com>
Date: Tue, 21 Apr 2026 09:40:39 +0100
Subject: [PATCH 5/6] test: add round-trip coverage + polish
 FileUploadResult/PreparedUpload
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses review feedback:

- **End-to-end round-trip test (wave-batch)**: a small file is prepared as
  `Visibility::Public`, signed via the testnet wallet, finalized, then
  retrieved using only `data_map_fetch(&data_map_address)` + `file_download`.
  Asserts the downloaded bytes match the original. This is the half of the
  contract the existing test didn't cover: not just that the address is
  recorded, but that it actually refers to a retrievable DataMap.

- **`#[non_exhaustive]` on `FileUploadResult` and `PreparedUpload`**: adding
  `data_map_address` was already technically a breaking change for any
  downstream that struct-literal-constructed these; `#[non_exhaustive]`
  forecloses the same concern for the next field.

- **`AlreadyStored` data-map-chunk visibility**: when the serialized
  `DataMap` hashes to a chunk that's already on the network (same file
  uploaded twice — plausible under deterministic self-encryption), the
  prepare step silently drops it from `prepared_chunks` while keeping
  `data_map_address = Some(addr)`. An `info!` now explicitly logs this,
  and the `data_map_address` doc comments clarify that `Some` means
  "retrievable", not "we paid to store it".

Merkle-path round-trip was attempted but blocked on an upstream
`WrongPoolCount` contract revert between `pay_for_merkle_tree` and the
`PaymentVaultV2` contract — reproduces outside this PR's changes and is
not caused by anything here. Removing the failing test; calling it out
separately for follow-up so the pool-commitment / depth relationship can
be investigated without holding up this PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ant-core/src/data/client/file.rs | 46 +++++++++++++++---
 ant-core/tests/e2e_file.rs       | 83 ++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+), 8 deletions(-)

diff --git a/ant-core/src/data/client/file.rs b/ant-core/src/data/client/file.rs
index 5dcac25..5b95bb4 100644
--- a/ant-core/src/data/client/file.rs
+++ b/ant-core/src/data/client/file.rs
@@ -391,7 +391,12 @@ pub enum Visibility {
 }
 
 /// Result of a file upload: the `DataMap` needed to retrieve the file.
+///
+/// Marked `#[non_exhaustive]` so adding a new field in future is not a
+/// breaking change for downstream consumers that construct or pattern-match
+/// on this struct.
 #[derive(Debug, Clone)]
+#[non_exhaustive]
 pub struct FileUploadResult {
     /// The data map containing chunk metadata for reconstruction.
     pub data_map: DataMap,
@@ -403,9 +408,13 @@ pub struct FileUploadResult {
     pub storage_cost_atto: String,
     /// Total gas cost in wei. 0 if no on-chain transactions were made.
     pub gas_cost_wei: u128,
-    /// Chunk address of the serialized `DataMap`, set only for [`Visibility::Public`]
-    /// uploads. Share this address so others can retrieve the file without the
-    /// local `DataMap` (via [`Client::data_map_fetch`] then [`Client::file_download`]).
+    /// Chunk address of the serialized `DataMap`, set only for
+    /// [`Visibility::Public`] uploads. **`Some` means this address is
+    /// retrievable from the network (via [`Client::data_map_fetch`])**, not
+    /// necessarily that *this* upload paid to store it — if the serialized
+    /// `DataMap` hashed to a chunk that was already on the network (same
+    /// file uploaded before; deterministic via self-encryption), the address
+    /// is still returned but no storage payment was made for it.
     pub data_map_address: Option<[u8; 32]>,
 }
 
@@ -439,17 +448,22 @@ pub enum ExternalPaymentInfo {
 /// Note: This struct stays in Rust memory — only the public fields of
 /// `payment_info` are sent to the frontend. `PreparedChunk` contains
 /// non-serializable network types, so the full struct cannot derive `Serialize`.
+///
+/// Marked `#[non_exhaustive]` so adding a new field in future is not a
+/// breaking change for downstream consumers.
 #[derive(Debug)]
+#[non_exhaustive]
 pub struct PreparedUpload {
     /// The data map for later retrieval.
     pub data_map: DataMap,
     /// Payment information — either wave-batch or merkle depending on chunk count.
     pub payment_info: ExternalPaymentInfo,
-    /// Chunk address of the serialized `DataMap` when this upload was prepared
-    /// with [`Visibility::Public`]. The address is `Some` whenever the data
-    /// map chunk has been bundled into `payment_info` for payment; it is
-    /// carried through to [`FileUploadResult::data_map_address`] after
-    /// finalization.
+    /// Chunk address of the serialized `DataMap` when this upload was
+    /// prepared with [`Visibility::Public`]. `Some` means the address is
+    /// retrievable on the network after finalization — either because this
+    /// upload paid to store the chunk in `payment_info`, or because the
+    /// chunk was already on the network (deterministic self-encryption).
+    /// Carried through to [`FileUploadResult::data_map_address`].
     pub data_map_address: Option<[u8; 32]>,
 }
 
@@ -686,6 +700,22 @@ impl Client {
                 }
             }
 
+            // Surface the "DataMap chunk was already on the network" case
+            // so debugging "why is data_map_address set but no storage cost
+            // appears for it?" doesn't require reading the source. See the
+            // `data_map_address` doc comment for why this is still a valid
+            // `Some(addr)` outcome.
+            if let Some(addr) = data_map_address {
+                if !prepared_chunks.iter().any(|c| c.address == addr) {
+                    info!(
+                        "Public upload: DataMap chunk {} was already stored \
+                         on the network — address is retrievable without a \
+                         new payment",
+                        hex::encode(addr)
+                    );
+                }
+            }
+
             let payment_intent = PaymentIntent::from_prepared_chunks(&prepared_chunks);
 
             info!(
diff --git a/ant-core/tests/e2e_file.rs b/ant-core/tests/e2e_file.rs
index 4d61c02..fb06897 100644
--- a/ant-core/tests/e2e_file.rs
+++ b/ant-core/tests/e2e_file.rs
@@ -5,7 +5,9 @@
 mod support;
 
 use ant_core::data::{compute_address, Client, ExternalPaymentInfo, Visibility};
+use evmlib::common::{QuoteHash, TxHash};
 use serial_test::serial;
+use std::collections::HashMap;
 use std::io::Write;
 use std::path::PathBuf;
 use std::sync::Arc;
@@ -217,3 +219,84 @@ async fn test_file_prepare_upload_visibility() {
     drop(client);
     testnet.teardown().await;
 }
+
+/// Full public-upload round-trip (wave-batch path).
+///
+/// Simulates the external-signer flow end-to-end: prepare → sign payments
+/// via the testnet wallet → finalize → `data_map_fetch` using only the
+/// returned address → `file_download` → assert recovered bytes equal the
+/// original. Proves the data_map_address actually refers to a retrievable
+/// DataMap on the network, not just a hash recorded in memory.
+#[tokio::test(flavor = "multi_thread")]
+#[serial]
+async fn test_public_upload_round_trip_wave_batch() {
+    let (client, testnet) = setup().await;
+
+    let original = vec![0x5au8; 4096];
+    let mut input_file = NamedTempFile::new().expect("create temp file");
+    input_file.write_all(&original).expect("write temp file");
+    input_file.flush().expect("flush temp file");
+
+    // Phase 1: prepare as public.
+    let prepared = client
+        .file_prepare_upload_with_visibility(input_file.path(), Visibility::Public)
+        .await
+        .expect("public prepare should succeed");
+    let data_map_address = prepared
+        .data_map_address
+        .expect("public prepare must record the DataMap address");
+
+    // Phase 2: simulate an external signer by paying for the quotes with the
+    // testnet wallet and collecting the resulting (quote_hash, tx_hash) map.
+    let payments = match &prepared.payment_info {
+        ExternalPaymentInfo::WaveBatch { payment_intent, .. } => payment_intent.payments.clone(),
+        other => panic!("expected wave-batch payment for a 4KB file, got {other:?}"),
+    };
+    let (tx_hash_map, _gas) = testnet
+        .wallet()
+        .pay_for_quotes(payments)
+        .await
+        .expect("testnet wallet should pay for quotes");
+    let tx_hash_map: HashMap<QuoteHash, TxHash> = tx_hash_map.into_iter().collect();
+
+    // Phase 3: finalize. The data map chunk is stored alongside the data
+    // chunks in this single call — no second network trip needed.
+    let result = client
+        .finalize_upload(prepared, &tx_hash_map)
+        .await
+        .expect("finalize_upload should succeed");
+    assert_eq!(
+        result.data_map_address,
+        Some(data_map_address),
+        "FileUploadResult must carry the DataMap address forward from PreparedUpload"
+    );
+
+    // Phase 4: a fresh retriever can fetch the data map using only the
+    // shared address — they did not participate in the upload.
+    let fetched_data_map = client
+        .data_map_fetch(&data_map_address)
+        .await
+        .expect("data_map_fetch must retrieve the stored DataMap");
+
+    // Phase 5: download + verify content.
+    let output_dir = TempDir::new().expect("create output temp dir");
+    let output_path = output_dir.path().join("round_trip_out.bin");
+    let bytes_written = client
+        .file_download(&fetched_data_map, &output_path)
+        .await
+        .expect("file_download should succeed");
+    assert_eq!(
+        bytes_written,
+        original.len() as u64,
+        "bytes_written should equal original size"
+    );
+
+    let downloaded = std::fs::read(&output_path).expect("read downloaded file");
+    assert_eq!(
+        downloaded, original,
+        "downloaded bytes must equal the original file"
+    );
+
+    drop(client);
+    testnet.teardown().await;
+}

From 200b49c8c5533ae7b8fa30d9dd386319a0f4f953 Mon Sep 17 00:00:00 2001
From: Chris O'Neil <chriso83@protonmail.com>
Date: Wed, 22 Apr 2026 23:22:21 +0100
Subject: [PATCH 6/6] chore: bump ant-cli to 0.2.0-rc.1

Point ant-node at WithAutonomi/ant-node rc-2026.4.2 branch and refresh
Cargo.lock.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Cargo.lock          | 18 +++++++++---------
 ant-cli/Cargo.toml  |  2 +-
 ant-core/Cargo.toml |  2 +-
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 4ea03ec..5e1f8d9 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -828,7 +828,7 @@ dependencies = [
 
 [[package]]
 name = "ant-cli"
-version = "0.1.6"
+version = "0.2.0-rc.1"
 dependencies = [
  "ant-core",
  "anyhow",
@@ -904,8 +904,8 @@ dependencies = [
 
 [[package]]
 name = "ant-node"
-version = "0.10.1"
-source = "git+https://github.com/withAutonomi/ant-node.git?branch=mick%2Falways-masque-relay-rebased#5d25e1f1ac91cd82d24116a085dfc1c26d0096ae"
+version = "0.11.0-rc.1"
+source = "git+https://github.com/WithAutonomi/ant-node.git?branch=rc-2026.4.2#2ba556e4af1b606ed2cf52c01674060cb0ab8ce3"
 dependencies = [
  "aes-gcm-siv",
  "blake3",
@@ -4988,9 +4988,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.38"
+version = "0.23.39"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69f9466fb2c14ea04357e91413efb882e2a6d4a406e625449bc0a5d360d53a21"
+checksum = "7c2c118cb077cca2822033836dfb1b975355dfb784b5e8da48f7b6c5db74e60e"
 dependencies = [
  "aws-lc-rs",
  "log",
@@ -5126,8 +5126,8 @@ dependencies = [
 
 [[package]]
 name = "saorsa-core"
-version = "0.22.0"
-source = "git+https://github.com/saorsa-labs/saorsa-core.git?branch=mick%2Falways-masque-relay-rebased#d37491fd2ead4b2e81f85a8d3c43e707bbafacc7"
+version = "0.24.0-rc.1"
+source = "git+https://github.com/saorsa-labs/saorsa-core.git?branch=rc-2026.4.2#a2813e83526c70048f5a564848b05e8088d786e4"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -5240,8 +5240,8 @@ dependencies = [
 
 [[package]]
 name = "saorsa-transport"
-version = "0.31.0"
-source = "git+https://github.com/saorsa-labs/saorsa-transport.git?branch=mick%2Falways-masque-relay-rebased#ec163406f526f42667f12a1ed4f5b6ec0ed4e02e"
+version = "0.33.0-rc.1"
+source = "git+https://github.com/saorsa-labs/saorsa-transport.git?branch=rc-2026.4.2#8b44b242fd62023c1a96728382ddd72917a63a4a"
 dependencies = [
  "anyhow",
  "async-trait",
diff --git a/ant-cli/Cargo.toml b/ant-cli/Cargo.toml
index 92264d2..6c559e5 100644
--- a/ant-cli/Cargo.toml
+++ b/ant-cli/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "ant-cli"
-version = "0.1.6"
+version = "0.2.0-rc.1"
 edition = "2021"
 
 [[bin]]
diff --git a/ant-core/Cargo.toml b/ant-core/Cargo.toml
index 9b2ac3f..dd9d243 100644
--- a/ant-core/Cargo.toml
+++ b/ant-core/Cargo.toml
@@ -38,7 +38,7 @@ tracing = "0.1"
 bytes = "1"
 lru = "0.16"
 rand = "0.8"
-ant-node = { git = "https://github.com/withAutonomi/ant-node.git", branch = "mick/always-masque-relay-rebased" }
+ant-node = { git = "https://github.com/WithAutonomi/ant-node.git", branch = "rc-2026.4.2" }
 saorsa-pqc = "0.5"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }