# 2026-03-17 Update Log

## Summary

Enhanced REST request logging to capture client network identity in Winston logs, enabled proxy-aware IP resolution, and reduced Fulcrum error-log noise for expected missing-transaction requests.

## Changes Made

- Updated `bin/server.js`:
  - Set Express proxy handling with `app.set('trust proxy', true)`.
  - Kept the current Winston request message format (`"${req.method} ${req.path}"`).
  - Added structured Winston metadata fields to request logs:
    - `client_ip` from `req.ip`
    - `remote_address` from `req.socket.remoteAddress`
- Updated `src/adapters/fulcrum-api.js`:
  - Added parsing helpers to normalize Fulcrum error messages from multiple response shapes.
  - Mapped common daemon missing-TX error (`No such mempool or blockchain transaction`) to:
    - status `404`
    - message `Transaction not found`
- Updated `src/use-cases/fulcrum-use-cases.js`:
  - Removed duplicate error logging in `getTransactionDetails()` and now rethrows adapter errors without a second error-level log.
- Updated `src/controllers/rest-api/fulcrum/controller.js`:
  - Added TXID validation (`64`-character hex) for `GET /v6/fulcrum/tx/data/:txid`.
  - Updated `handleError()` logging policy:
    - `Transaction not found` (`404`) logs at `info`
    - other `4xx` logs at `warn`
    - `5xx` logs at `error`

## Useful Fields Available for REST Request Logging

- Routing and request basics:
  - `method` (`req.method`)
  - `path` (`req.path`)
  - `original_url` (`req.originalUrl`)
  - `query` (`req.query`)
- Client network identity:
  - `client_ip` (`req.ip`)
  - `forwarded_ips` (`req.ips`, when behind one or more proxies)
  - `remote_address` (`req.socket.remoteAddress`)
- HTTP and transport:
  - `protocol` (`req.protocol`)
  - `secure` (`req.secure`)
  - `http_version` (`req.httpVersion`)
  - `host` (`req.get('host')`)
  - `origin` (`req.get('origin')`)
  - `referer` (`req.get('referer')`)
  - `user_agent` (`req.get('user-agent')`)
- Request/response performance and size:
  - `status_code` (`res.statusCode`, from `res.on('finish')`)
  - `duration_ms` (elapsed time between request start and response finish)
  - `request_size_bytes` (`req.get('content-length')`)
  - `response_size_bytes` (`res.getHeader('content-length')`)
- App-specific request context in this codebase:
  - `basic_auth_valid` (`req.locals.basicAuthValid`)
  - x402 decision/bypass status (derived from middleware path and config)

## Already Logging

- In Winston request logs:
  - `message` with method + path (for example `GET /v6/full-node/blockchain/getBlockCount`)
  - `client_ip`
  - `remote_address`
  - `timestamp` (from Winston timestamp formatter)
  - `level`
- In console endpoint logs:
  - Request line with method, path, and `req.ip`
  - Response line with method, path, and final `res.statusCode`

## Outcome

- Request logs now preserve existing behavior while adding IP attribution fields.
- `trust proxy` ensures `req.ip` is proxy-aware when the server is deployed behind a reverse proxy.
- The project now has a documented list of high-value request fields for future logging expansion.
- Fulcrum missing-transaction lookups now return cleaner API semantics (`404 Transaction not found`).
- Duplicate error logs for a single missing TX lookup were removed.
- Invalid TXIDs are rejected early with a `400` validation error.