psf-bch-api/dev-docs/update-logs/2026-03-17.md

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.