docs: update rate limiting docs for RealIpKeyExtractor and trusted proxy

- Correct per-endpoint rate limit tables to reflect actual single global config
- Document RealIpKeyExtractor behavior (X-Real-IP / X-Forwarded-For behind proxy)
- Add BAL_SERVER_TRUSTED_PROXY env var to all relevant docs
- Update security audit and modules detail with proxy-aware rate limiting

README.md

@@ -112,6 +112,7 @@ The `bal-server` application can be configured using environment variables.
 | `BAL_SERVER_ACTIX_DEFAULT_BURST` | Rate limit: default burst size. | `100` |
 | `BAL_SERVER_ACTIX_WORKERS` | Number of Actix worker threads. | `4` |
 | `BAL_SERVER_ACTIX_MAX_CONNECTIONS` | Maximum concurrent connections. | `100` |
+| `BAL_SERVER_TRUSTED_PROXY` | Trusted reverse proxy IP for rate-limiting client identification. | `127.0.0.1` |
 
 ---
 

docs/04_modules_detail.md

@@ -117,7 +117,7 @@ The main application binary that provides an async HTTP server.
 
 ### Architecture
 - **Runtime:** `actix-web 4.9.0` with `actix-rt` (`#[actix_web::main]`).
-- **Rate Limiting:** `actix-governor` middleware with token-bucket algorithm per endpoint.
+- **Rate Limiting:** `actix-governor` middleware with token-bucket algorithm. Uses `RealIpKeyExtractor` to identify clients by real IP behind reverse proxy (via `X-Real-IP` / `X-Forwarded-For` headers).
 - **Response Compression:** `actix_web::middleware::Compress`.
 - **Request Logging:** `actix_web::middleware::Logger::default()`.
 - **Shared State:** `Arc<Mutex<Connection>>` for database access, `MyConfig` for configuration.
@@ -132,7 +132,7 @@ The main application binary that provides an async HTTP server.
 - `address` (xpub or address), `fixed_fee` (sats), `xpub` (bool), `network` (bitcoin::Network), `name`, `enabled`
 
 **`ActixConfig`** (server tuning):
-- `max_body_size`, `timeout_secs`, per-endpoint rate limits (`pushtxs`, `searchtx`, `info`, `default`), `workers`, `max_connections`
+- `max_body_size`, `timeout_secs`, rate limits (`pushtxs` per sec/burst), `workers`, `max_connections`, `trusted_proxy`
 
 ### Key Routes
 | Method | Path | Handler | Description |

docs/05_api_reference.md

@@ -10,16 +10,11 @@
 
 ### Rate Limiting
 
-All endpoints are rate-limited via `actix-governor` with a token-bucket algorithm. Defaults:
+All endpoints are rate-limited via `actix-governor` with a token-bucket algorithm. The rate limit key is the **real client IP address**, extracted from `X-Real-IP` / `X-Forwarded-For` headers when the request comes from a trusted proxy (default `127.0.0.1`, configurable via `BAL_SERVER_TRUSTED_PROXY`). Direct connections (non-proxy) use the TCP peer IP.
 
-| Endpoint | Rate (req/s) | Burst |
-|----------|-------------|-------|
-| `POST /{network}/pushtxs` | 1 | 3 |
-| `POST /searchtx` | 5 | 10 |
-| `GET /{network}/info` | 20 | 30 |
-| All others | 50 | 100 |
+Default: 1 req/s with burst of 3 (configurable via `BAL_SERVER_ACTIX_PUSHTXS_PER_SEC` / `BAL_SERVER_ACTIX_PUSHTXS_BURST`).
 
-Rate limits are configurable via `BAL_SERVER_ACTIX_*` environment variables.
+When behind Nginx, ensure `proxy_set_header X-Real-IP $remote_addr` is set so the server can identify individual clients.
 
 ### `GET /`
 - **Description:** Returns a static identification string (default: "Will Executor Server").

docs/07_deployment_and_ops.md

@@ -40,8 +40,9 @@ Example: `BAL_SERVER_REGTEST_ADDRESS=tpub...`, `BAL_SERVER_BITCOIN_FIXED_FEE=500
 | `BAL_SERVER_ACTIX_TIMEOUT_SECS` | `5` | Request timeout in seconds |
 | `BAL_SERVER_ACTIX_WORKERS` | `4` | Number of actix-web worker threads |
 | `BAL_SERVER_ACTIX_MAX_CONNECTIONS` | `100` | Maximum concurrent connections |
-| `BAL_SERVER_ACTIX_PUSHTXS_PER_SEC` | `1` | Rate limit: pushtxs requests per second |
-| `BAL_SERVER_ACTIX_PUSHTXS_BURST` | `3` | Rate limit: pushtxs burst size |
+| `BAL_SERVER_TRUSTED_PROXY` | `127.0.0.1` | Trusted reverse proxy IP for rate-limiting client identification |
+| `BAL_SERVER_ACTIX_PUSHTXS_PER_SEC` | `1` | Rate limit: requests per second (applied to all endpoints) |
+| `BAL_SERVER_ACTIX_PUSHTXS_BURST` | `3` | Rate limit: burst size (applied to all endpoints) |
 | `BAL_SERVER_ACTIX_SEARCHTX_PER_SEC` | `5` | Rate limit: searchtx requests per second |
 | `BAL_SERVER_ACTIX_SEARCHTX_BURST` | `10` | Rate limit: searchtx burst size |
 | `BAL_SERVER_ACTIX_INFO_PER_SEC` | `20` | Rate limit: info requests per second |

docs/08_security_audit.md

@@ -52,7 +52,7 @@
 **Description:** All DoS vectors mitigated via actix-web migration.
 **Mitigation Applied:**
 - Body size limit: `PayloadConfig::default().limit(max_body_size)` via `BAL_SERVER_ACTIX_MAX_BODY_SIZE` (default 1 MiB).
-- Rate limiting: `actix-governor` with token-bucket per endpoint (`BAL_SERVER_ACTIX_PUSHTXS_PER_SEC`/`BURST`).
+- Rate limiting: `actix-governor` with token-bucket per client IP (`BAL_SERVER_ACTIX_PUSHTXS_PER_SEC`/`BURST`). Uses `RealIpKeyExtractor` to extract real client IP from proxy headers.
 - Connection limits: `workers(4)` and `max_connections(100)` via `BAL_SERVER_ACTIX_WORKERS`/`MAX_CONNECTIONS`.
 - Body timeout: configurable via `BAL_SERVER_ACTIX_TIMEOUT_SECS`.
 - ZMQ timeout: `set_rcvtimeo(5000)` prevents infinite blocking.
@@ -130,7 +130,7 @@
 6. Use read-only filesystem for the server binary.
 
 ### Application-Level
-1. **Rate Limiting:** Implemented via `actix-governor` with per-endpoint token-bucket configuration.
+1. **Rate Limiting:** Implemented via `actix-governor` with token-bucket per client IP. `RealIpKeyExtractor` identifies clients behind reverse proxy using `X-Real-IP` / `X-Forwarded-For` headers. Trusted proxy IP configurable via `BAL_SERVER_TRUSTED_PROXY`.
 2. **Input Validation:** Network enum check, txid hex validation, body size limits.
 3. **HTTPS:** Via Nginx reverse proxy with Let's Encrypt.
 4. **WAL Mode:** Enabled with retry logic for concurrent access.