Logging

NOOSChain uses a global Pino-based logger for runtime transparency. The goal is to make normal node startup, API traffic, consensus, sync, gossip, backfill, and verification behavior explainable without exposing private material.

Defaults

npm run dev logs to the console by default.

Development defaults:

• console logging enabled
• pretty format
• timestamped lines
• level info

Production defaults:

• console logging enabled
• JSON format
• timestamped lines
• level info

Fastify request logging uses the same logger instance as the rest of the node, so request lines and subsystem lines share the same timestamp, node context, and redaction policy.

Configuration

Env var	Default	Meaning
NOOS_LOG_LEVEL	info	Minimum log level. Common values are debug, info, warn, and error.
NOOS_LOG_FORMAT	pretty in development, json in production	Console/file log format. Use json for ingestion by log collectors.
NOOS_LOG_TIMESTAMPS	true	Adds ISO timestamps to log records.
NOOS_LOG_CONSOLE_ENABLED	true	Enables stdout/stderr console logging.
NOOS_LOG_FILE_ENABLED	false	Enables a JSON file sink.
NOOS_LOG_FILE_PATH	./logs/nooschain.log	File sink path. Parent directories are created automatically.
NOOS_LOG_FILE_LEVEL	NOOS_LOG_LEVEL	Minimum level for file logs.
NOOS_LOG_EVENTS_ENABLED	false	Enables an additional JSONL event sink for operators that want a separate operational event stream.
NOOS_LOG_EVENTS_PATH	./logs/nooschain-events.jsonl	Event sink path.

Example PowerShell development run with verbose sync/gossip visibility:

$env:NOOS_LOG_LEVEL="debug"
$env:NOOS_LOG_FORMAT="pretty"
npm run dev

Example production-style JSON file logging:

$env:NOOS_LOG_FORMAT="json"
$env:NOOS_LOG_FILE_ENABLED="true"
$env:NOOS_LOG_FILE_PATH="C:\nooschain\logs\node-a.log"
npm run dev

Categories

Every runtime log record includes a component field. The most important categories are:

Component	What it describes
system	process startup, shutdown, server listen failures
api	HTTP server and request logging
config	startup warnings and safety policy decisions
consensus	consensus adapter lifecycle and status
sync	peer block sync lifecycle, batches, incidents, and results
gossip	transaction gossip admission and propagation outcomes
backfill	permission-gated payload availability fetches
peers	operator peer actions, peer scoring actions, and incident resolution markers
snapshots	HTTP snapshot import attempts and disabled HTTP export attempts
observability	debug-level timing/error records for observability resources
execution	deterministic block execution warnings, including SMT cache guards
chain-verification	scheduled chain verification failures

Runtime node context is also attached where available:

• nodeId
• nodeRole
• chainId
• consensusMode

What Is Logged

The logger records operational facts, not sensitive data. Examples:

• server startup mode, TLS/mTLS status, CORS origin count
• consensus adapter start/stop
• sync run start/end, active peer count, heights, synced block counts
• skipped sync while incident mode is active
• gossip transaction hashes, types, propagation success/failure, rejection reason
• backfill attempted/fetched/skipped/failed counters
• peer ids and node ids involved in sync/gossip/backfill
• operator-triggered peer actions: add, disable, quarantine, unquarantine, ban, unban, and score reset
• operator-triggered manual sync/backfill and refusal while incident mode is active
• operator-triggered chain verification runs and verification outcome counts
• HTTP snapshot export refusal and HTTP snapshot import attempts/completion
• observability endpoint timing at debug level
• SMT cache guard warnings

Operator Actions

Operator mutations are logged as operational events, but the logger records only the action metadata needed for audit/debugging:

• operator auth method (bearer_token or development fallback)
• peer ids and node ids
• incident ids
• snapshot hash/height
• sync/backfill counters
• verification result counts

Request bodies are not dumped into logs. For example, snapshot import logs the snapshot hash and height, not the snapshot document; payload backfill logs record ids and counters, not ciphertext bytes.

Redaction

The logger redacts sensitive-looking fields before writing to any sink.

Redacted keys include:

• privateKey, private_key, NODE_PRIVATE_KEY
• token, NOOS_OPERATOR_TOKEN
• secret
• password
• challenge
• dek, DEK
• encryptedPayload, encrypted_payload
• plaintext
• authorization and cookies in request headers

The rule is intentionally conservative. If a field name looks sensitive, it is redacted even when the value is harmless.

File And Event Sinks

The normal file sink is intended for general node logs. The event sink is a second JSONL stream that can be enabled when operators want to collect compact runtime events separately from console output.

Both sinks use asynchronous file writes. They should be placed on local disk in production deployments and rotated by the host process manager or log agent.

Development Warnings

When TLS is disabled outside production, the startup warning now goes through the config logger category instead of raw console.warn. Production TLS requirements still fail startup when the required TLS settings are missing.

Tests

Logging behavior is covered by:

npm run test:logging

The test verifies file/event sinks, component context, node context, and redaction of private keys, tokens, DEKs, plaintext, and encrypted payload bytes.