chore: sync all changes to Gitea

- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor

docs/09-troubleshooting/DAPP_CONSOLE_ERRORS_METAMASK.md

@@ -0,0 +1,42 @@
+# DApp Console Errors — MetaMask (ObjectMultiplex / StreamMiddleware)
+
+**Last updated:** 2026-02-22
+
+## What you might see
+
+In the browser console when using the DApp with MetaMask you may see:
+
+- **ObjectMultiplex - malformed chunk without name "ACK"**
+- **StreamMiddleware - Unknown response id "…"**
+- **MetaMask: Lost connection to "MetaMask RpcProvider"**
+- **MetaMask: Disconnected from MetaMask background. Page reload required.**
+
+These messages come from **MetaMask’s inpage script** (`inpage.js`) and the extension’s internal stream protocol, not from the DApp’s application code.
+
+## Cause
+
+- The **ObjectMultiplex** and **StreamMiddleware** messages are from the extension’s JSON-RPC stream (page ↔ MetaMask background). They can appear when:
+  - The extension is updated or restarted
+  - The tab is backgrounded for a long time
+  - Multiple wallet extensions (e.g. MetaMask + MetaMask Flask) are installed
+  - The browser or extension has a temporary glitch
+- **“Lost connection” / “Disconnected from MetaMask background”** means the content script lost its connection to the extension’s background page (e.g. user locked MetaMask, restarted the extension, or the extension crashed).
+
+## What we did in the DApp
+
+- **We cannot fix or suppress these errors inside the DApp** — they are emitted by the MetaMask extension.
+- We added **user-facing handling** so that when the wallet disconnects unexpectedly, the DApp shows a toast:  
+  **“Wallet disconnected. Please reconnect or reload the page.”**  
+  This does not show when the user explicitly clicks **Disconnect** in the DApp.
+
+## What you can do
+
+1. **Reload the page** after a “Lost connection” error, then click **Connect Wallet** again.
+2. **Use a single MetaMask build** (e.g. disable MetaMask Flask if you don’t need it) to reduce stream conflicts.
+3. **Update MetaMask** to the latest version.
+4. **Ignore the ObjectMultiplex/StreamMiddleware messages** if the DApp still connects and works after a reload.
+
+## References
+
+- MetaMask inpage provider: content script that injects `window.ethereum` and uses a multiplexed stream to the background page.
+- Wagmi/viem in the DApp use this provider; when the extension drops the connection, wagmi’s `useAccount()` eventually reports `isConnected: false`, which we use to show the disconnect toast.

docs/09-troubleshooting/PUBLIC_RPC_WEBSOCKET_502.md

@@ -0,0 +1,27 @@
+# Public RPC WebSocket 502 / upgrade_502
+
+**Status:** Proxy/ingress configuration issue (not the RPC nodes themselves).
+
+## What you see
+
+- **Script:** `scripts/verify/check-public-rpc-stability-e2e.sh` reports WebSocket endpoints as **warn** with `upgrade_502`.
+- **Meaning:** The HTTPS→WebSocket upgrade request to the public WSS URL returns HTTP **502 Bad Gateway** from the reverse proxy (e.g. NPMplus, Cloudflare, or ingress in front of the RPC).
+
+## Cause
+
+- RPC nodes (e.g. VMID 2201) serve WebSocket on port 8546 and are healthy.
+- The **public** WSS URLs (e.g. `wss://rpc-ws-pub.d-bis.org`) go through a proxy. If the proxy is not configured to forward WebSocket upgrades correctly, or the upstream is unreachable from the proxy, the proxy returns 502.
+
+## What to do
+
+1. **Confirm RPC is fine:** Run `scripts/health/check-rpc-vms-health.sh` and `scripts/test-all-rpc-nodes.py` — both should pass. HTTP public RPC usually passes (5/5).
+2. **Fix proxy/ingress:** On the host that serves the public WSS hostname (e.g. NPMplus or Cloudflare Tunnel):
+   - Ensure the proxy has **WebSocket support** enabled for that host.
+   - Ensure the proxy upstream points to the correct RPC host:port (e.g. `http://192.168.11.221:8546` or the internal hostname) and that the proxy can reach it.
+   - Restart the proxy after config changes.
+3. **Full WebSocket test:** Install `wscat` where you run the E2E check: `npm i -g wscat` (or use `npx -y wscat`). The script will then run a full WebSocket JSON-RPC test; if the proxy still returns 502, the failure is at the proxy, not wscat.
+
+## Related
+
+- **HTTP public RPC:** If those pass, the RPC nodes and HTTP proxy path are OK; only the WebSocket path needs proxy fix.
+- **Config:** See `docs/04-configuration/cloudflare/` and NPMplus proxy host settings for WSS domains.

docs/09-troubleshooting/README.md

@@ -1,31 +0,0 @@
-# Troubleshooting
-
-**Last Updated:** 2026-01-31  
-**Document Version:** 1.0  
-**Status:** Active Documentation
-
----
-
-This directory contains troubleshooting guides and FAQs.
-
-## Documents
-
-- **[TROUBLESHOOTING_FAQ.md](TROUBLESHOOTING_FAQ.md)** ⭐⭐⭐ - Common issues and solutions - **Start here for problems**
-- **[RPC_NODES_BLOCK_PRODUCTION_FIX.md](RPC_NODES_BLOCK_PRODUCTION_FIX.md)** ⭐⭐ - RPC nodes not responding; **ping works but curl doesn’t** (use POST + JSON-RPC; see section “Ping works but curl to :8545 doesn’t?”)
-- **[METAMASK_TROUBLESHOOTING_GUIDE.md](METAMASK_TROUBLESHOOTING_GUIDE.md)** ⭐⭐ - MetaMask on Chain 138 (RPC, tokens, swaps, XChain error)
-- **[QBFT_TROUBLESHOOTING.md](QBFT_TROUBLESHOOTING.md)** ⭐⭐ - QBFT consensus troubleshooting
-
-## Quick Reference
-
-**Common Issues:**
-1. Check TROUBLESHOOTING_FAQ.md for common problems
-2. For consensus issues, see QBFT_TROUBLESHOOTING.md
-3. For allowlist issues, see [../06-besu/BESU_ALLOWLIST_QUICK_START.md](../06-besu/BESU_ALLOWLIST_QUICK_START.md)
-4. **MetaMask "No XChain Swaps native asset found for chainId: eip155:138"** (on **Send** or Swap) — see [METAMASK_TROUBLESHOOTING_GUIDE.md](METAMASK_TROUBLESHOOTING_GUIDE.md#7-swap--bridge-in-wallet--and-send); workaround: send from a dApp, try another Send entry point, or use another wallet
-
-## Related Documentation
-
-- **[../03-deployment/OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md)** - Operational procedures
-- **[../06-besu/](../06-besu/)** - Besu configuration
-- **[../08-monitoring/](../08-monitoring/)** - Monitoring guides
-