README: update known issues and add inbound network ports (#2373)

* README: update known issues

* Add ticket numbers

* Add network ports to README

* Make heading a bit clearer

* Update zebra listener address docs

Explain how Zebra currently uses listener addresses,
after recent changes.

README.md

@@ -82,7 +82,18 @@ We usually run `zebrad` on systems with:
 `zebrad` might build and run fine on smaller and slower systems - we haven't
 tested its exact limits yet.
 
-### Network Usage
+### Network Ports and Data Usage
+
+By default, Zebra uses the following inbound TCP listener ports:
+- 8233 on Mainnet
+- 18233 on Testnet
+
+If Zebra is configured with a specific [`listen_addr`](https://doc.zebra.zfnd.org/zebra_network/struct.Config.html#structfield.listen_addr),
+it will advertise this address to other nodes for inbound connections.
+
+Zebra makes outbound connections to peers on any port.
+But `zcashd` prefers peers on the default ports,
+so that it can't be used for DDoS attacks on other networks.
 
 `zebrad`'s typical network usage is:
 - initial sync: 30 GB download
@@ -128,11 +139,16 @@ Zebra primarily depends on pure Rust crates, and some Rust/C++ crates:
 ### Known Issues
 
 There are a few bugs in Zebra that we're still working on fixing:
-- [Peer connections sometimes fail permanently #1435](https://github.com/ZcashFoundation/zebra/issues/1435)
-  - these permanent failures can happen after a network disconnection, sleep, or individual peer disconnections
-  - workaround: use `Control-C` to exit `zebrad`, and then restart `zebrad`
+- [In rare cases, Zebra panics on shutdown #1678](https://github.com/ZcashFoundation/zebra/issues/1678)
+  - For examples, see [#2055](https://github.com/ZcashFoundation/zebra/issues/2055) and [#2209](https://github.com/ZcashFoundation/zebra/issues/2209)
+  - These panics can be ignored, unless they happen frequently
+- [Interrupt handler does not work when a blocking task is running #1351](https://github.com/ZcashFoundation/zebra/issues/1351)
+  - Zebra should eventually exit once the task finishes. Or you can forcibly terminate the process.
 - [Duplicate block errors #1372](https://github.com/ZcashFoundation/zebra/issues/1372)
-  - these errors can be ignored, unless they happen frequently
+  - These errors can be ignored, unless they happen frequently
+
+Zebra's state commits changes using database transactions.
+If you forcibly terminate it, or it panics, any incomplete changes will be rolled back the next time it starts.
 
 ## Future Work
 

zebra-network/src/config.rs

@@ -11,8 +11,8 @@ use zebra_chain::{parameters::Network, serialization::canonical_socket_addr};
 
 use crate::BoxError;
 
-/// The number of times Zebra will retry each initial peer, before checking if
-/// any other initial peers have returned addresses.
+/// The number of times Zebra will retry each initial peer's DNS resolution,
+/// before checking if any other initial peers have returned addresses.
 const MAX_SINGLE_PEER_RETRIES: usize = 2;
 
 /// Configuration for networking code.
@@ -22,12 +22,21 @@ pub struct Config {
     ///
     /// Can be `address:port` or just `address`. If there is no configured
     /// port, Zebra will use the default port for the configured `network`.
+    ///
     /// `address` can be an IP address or a DNS name. DNS names are
     /// only resolved once, when Zebra starts up.
     ///
-    /// Zebra will also advertise this address to other nodes. Advertising a
-    /// different external IP address is currently not supported, see #1890
-    /// for details.
+    /// If a specific listener address is configured, Zebra will advertise
+    /// it to other nodes. But by default, Zebra uses an unspecified address
+    /// ("0.0.0.0" or "[::]"), which is not advertised to other nodes.
+    ///
+    /// Zebra does not currently support:
+    /// - [Advertising a different external IP address #1890](https://github.com/ZcashFoundation/zebra/issues/1890), or
+    /// - [Auto-discovering its own external IP address #1893](https://github.com/ZcashFoundation/zebra/issues/1893).
+    ///
+    /// However, other Zebra instances compensate for unspecified or incorrect
+    /// listener addresses by adding the external IP addresses of peers to
+    /// their address books.
     pub listen_addr: SocketAddr,
 
     /// The network to connect to.