@aztec-labs/foundation 6.0.0-nightly.20260829

package/src/log/bigint-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Converts bigint values to strings recursively in a log object to avoid serialization issues.
+ */
+export function convertBigintsToStrings(obj: unknown): unknown {
+  if (typeof obj === 'bigint') {
+    return String(obj);
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => convertBigintsToStrings(item));
+  }
+
+  if (obj !== null && typeof obj === 'object') {
+    if (typeof (obj as any).toJSON === 'function') {
+      return convertBigintsToStrings((obj as any).toJSON());
+    }
+    const result: Record<string, unknown> = {};
+    for (const key in obj) {
+      result[key] = convertBigintsToStrings((obj as Record<string, unknown>)[key]);
+    }
+    return result;
+  }
+
+  return obj;
+}

package/src/log/console.ts

@@ -0,0 +1,42 @@
+/* eslint-disable no-console */
+import type { LogFn } from './log_fn.js';
+
+/**
+ * ConsoleLogger is a utility class that provides customizable console logging functionality.
+ * It allows setting a custom prefix for log messages and an optional custom logger function,
+ * which can be useful for controlling the format of the output or redirecting logs to a different destination.
+ */
+class ConsoleLogger {
+  constructor(
+    private prefix: string,
+    private logger: (...args: any[]) => void = console.log,
+  ) {}
+
+  /**
+   * Log messages with the specified prefix using the provided logger.
+   * By default, it uses 'console.log' as the logger but can be overridden
+   * during ConsoleLogger instantiation. This method allows for easy
+   * organization and readability of log messages in the console.
+   *
+   * @param args - The data to be logged, any number of arguments can be passed to this function.
+   */
+  public log(...args: any[]) {
+    this.logger(`${this.prefix}:`, ...args);
+  }
+}
+
+/**
+ * Creates a Logger function with an optional prefix for log messages.
+ * If a prefix is provided, the created logger will prepend it to each log message.
+ * If no prefix is provided, the default console.log will be returned.
+ *
+ * @param prefix - The optional string to prepend to each log message.
+ * @returns A Logger function that accepts any number of arguments and logs them with the specified prefix.
+ */
+export function createConsoleLogger(prefix?: string): LogFn {
+  if (prefix) {
+    const logger = new ConsoleLogger(prefix, console.log);
+    return (...args: any[]) => logger.log(...args);
+  }
+  return console.log;
+}

package/src/log/gcloud-logger-config.ts

@@ -0,0 +1,72 @@
+import type { pino } from 'pino';
+
+import { convertBigintsToStrings } from './bigint-utils.js';
+
+/* eslint-disable camelcase */
+
+const GOOGLE_CLOUD_TRACE_ID = 'logging.googleapis.com/trace';
+const GOOGLE_CLOUD_SPAN_ID = 'logging.googleapis.com/spanId';
+const GOOGLE_CLOUD_TRACE_SAMPLED = 'logging.googleapis.com/trace_sampled';
+
+/**
+ * Pino configuration for google cloud observability. Tweaks message and timestamp,
+ * adds trace context attributes, and injects severity level.
+ * Adapted from https://cloud.google.com/trace/docs/setup/nodejs-ot#config-structured-logging.
+ */
+export const GoogleCloudLoggerConfig = {
+  messageKey: 'message',
+  formatters: {
+    log(object: Record<string, unknown>): Record<string, unknown> {
+      // Convert bigints to strings recursively to avoid serialization issues
+      object = convertBigintsToStrings(object) as Record<string, unknown>;
+
+      // Add trace context attributes following Cloud Logging structured log format described
+      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
+      const { trace_id, span_id, trace_flags, ...rest } = object;
+
+      if (trace_id && span_id) {
+        return {
+          [GOOGLE_CLOUD_TRACE_ID]: trace_id,
+          [GOOGLE_CLOUD_SPAN_ID]: span_id,
+          [GOOGLE_CLOUD_TRACE_SAMPLED]: trace_flags ? trace_flags === '01' : undefined,
+          trace_flags, // Keep the original trace_flags for otel-pino-stream
+          ...rest,
+        };
+      }
+      return object;
+    },
+    level(label: string, level: number): object {
+      // Inspired by https://github.com/pinojs/pino/issues/726#issuecomment-605814879
+      // Severity labels https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogSeverity
+      let severity: string;
+
+      switch (label as pino.Level | keyof CustomLevels) {
+        case 'trace':
+        case 'debug':
+        case 'verbose':
+          severity = 'DEBUG';
+          break;
+        case 'info':
+          severity = 'INFO';
+          break;
+        case 'warn':
+          severity = 'WARNING';
+          break;
+        case 'error':
+          severity = 'ERROR';
+          break;
+        case 'fatal':
+          severity = 'CRITICAL';
+          break;
+        default:
+          severity = 'DEFAULT';
+          break;
+      }
+
+      return { severity, level };
+    },
+  },
+} satisfies pino.LoggerOptions;
+
+// Define custom logging levels for pino. Duplicate from pino-logger.ts.
+type CustomLevels = { verbose: 25 };

package/src/log/index.ts

@@ -0,0 +1,6 @@
+export * from './console.js';
+export * from './libp2p_logger.js';
+export * from './log_fn.js';
+export * from './noir_debug_log_util.js';
+export * from './pino-logger.js';
+export * from './log-levels.js';

package/src/log/libp2p_logger.ts

@@ -0,0 +1,93 @@
+import type { ComponentLogger, Logger } from '@libp2p/interface';
+
+import { getLogLevelFromFilters } from './log-filters.js';
+import type { LogLevel } from './log-levels.js';
+import { type LoggerBindings, logFilters, logger } from './pino-logger.js';
+
+/**
+ * Creates a libp2p compatible logger that wraps our pino logger.
+ * This adapter implements the ComponentLogger interface required by libp2p.
+ * @param namespace - Base namespace for the logger
+ * @param bindings - Optional bindings to pass to the logger (actor, instanceId)
+ */
+export function createLibp2pComponentLogger(namespace: string, bindings?: LoggerBindings): ComponentLogger {
+  return {
+    forComponent: (component: string) => createLibp2pLogger(`${namespace}:${component}`, bindings),
+  };
+}
+
+// Lipp2p libraries use arbitrary string substitutions, so we need to replace them with %s, this is slow so avoid doing it unless trace debugging
+function replaceFormatting(message: string) {
+  // Message can sometimes not be a string, e.g. an error object, just return it as is
+  if (!message?.replace) {
+    return message;
+  }
+
+  return message.replace(/(%p|%a)/g, '%s');
+}
+
+function createLibp2pLogger(component: string, bindings?: LoggerBindings): Logger {
+  // Create a direct pino logger instance for libp2p that supports string interpolation
+  const actor = bindings?.actor;
+  const instanceId = bindings?.instanceId;
+  const log = logger.child(
+    { module: component, ...(actor && { actor }), ...(instanceId && { instanceId }) },
+    { level: getLogLevelFromFilters(logFilters, component) },
+  );
+
+  const logIfEnabled = (level: LogLevel, message: string, ...args: unknown[]) => {
+    if (!log.isLevelEnabled(level)) {
+      return;
+    }
+
+    log[level](replaceFormatting(message), ...formatArgs(message, args));
+  };
+
+  // Default log level is trace as this is super super noisy
+  const logFn = (message: string, ...args: unknown[]) => {
+    logIfEnabled('trace', message, ...args);
+  };
+
+  return Object.assign(logFn, {
+    enabled: log.isLevelEnabled('debug'),
+    error(message: string, ...args: unknown[]) {
+      // We write error outputs as debug as they are often expected, e.g. connection errors can happen in happy paths
+      logIfEnabled('debug', `error: ${message}`, ...args);
+    },
+
+    debug(message: string, ...args: unknown[]) {
+      logIfEnabled('debug', message, ...args);
+    },
+
+    info(message: string, ...args: unknown[]) {
+      logIfEnabled('info', message, ...args);
+    },
+
+    warn(message: string, ...args: unknown[]) {
+      logIfEnabled('warn', message, ...args);
+    },
+
+    trace(message: string, ...args: unknown[]) {
+      logIfEnabled('trace', message, ...args);
+    },
+  });
+}
+
+function formatArgs(message: string, args: unknown[]) {
+  if (!args) {
+    return args;
+  }
+  return args.map(arg => {
+    if (
+      typeof arg === 'object' &&
+      arg &&
+      'err' in arg &&
+      arg.err instanceof Error &&
+      'type' in arg.err &&
+      arg.err.type === 'AbortError'
+    ) {
+      delete arg.err; // Remove the AbortError from the logs
+    }
+    return arg;
+  });
+}

package/src/log/log-filters.ts

@@ -0,0 +1,81 @@
+import { type LogLevel, LogLevels } from './log-levels.js';
+
+export type LogFilters = [string, LogLevel][];
+
+export function getLogLevelFromFilters(filters: LogFilters, module: string): LogLevel | undefined {
+  for (const [filterModule, level] of filters) {
+    try {
+      const regex = new RegExp(filterModule);
+      if (regex.test(module)) {
+        return level as LogLevel;
+      }
+    } catch {
+      // If regex is invalid, fall back to startsWith check
+      if (module.startsWith(filterModule)) {
+        return level as LogLevel;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Parses the LOG_LEVEL env string into a default level and per-module filter overrides.
+ *
+ * Format: `<default_level>;<level>:<module1>,<module2>;<level>:<module3>;...`
+ * - First segment (before the first `;`) is the default log level for all modules.
+ * - Remaining segments are `level:module` pairs: apply the given level to the listed modules (comma-separated).
+ * - Later filters override earlier ones for overlapping module matches.
+ * - The `aztec:` prefix is stripped from module names; spaces are trimmed.
+ *
+ * @example
+ * ```ts
+ * parseLogLevel('debug;warn:module1,module2;error:module3', 'info')
+ * // => ['debug', [['module3', 'error'], ['module2', 'warn'], ['module1', 'warn']]]
+ * ```
+ */
+export function parseLogLevelEnvVar(
+  logLevelEnvVar: string | undefined,
+  defaultLevel: LogLevel,
+): [LogLevel, LogFilters] {
+  if (!logLevelEnvVar) {
+    return [defaultLevel, []];
+  }
+  const [level] = logLevelEnvVar.split(';', 1);
+  assertValidLogLevel(level);
+  return [level, parseFilters(logLevelEnvVar.slice(level.length + 1))];
+}
+
+function assertValidLogLevel(level: string): asserts level is LogLevel {
+  if (!LogLevels.includes(level as LogLevel)) {
+    throw new Error(`Invalid log level: ${level}`);
+  }
+}
+
+function parseFilters(definition: string | undefined): LogFilters {
+  if (!definition) {
+    return [];
+  }
+
+  const statements = definition.split(';');
+  const filters: LogFilters = [];
+  for (const statement of statements) {
+    const [level] = statement.split(':', 1);
+    const modules = statement.slice(level.length + 1);
+    if (!modules || !level) {
+      throw new Error(`Invalid log filter statement: ${statement}`);
+    }
+    const sanitizedLevel = level.trim().toLowerCase();
+    assertValidLogLevel(sanitizedLevel);
+    for (const module of modules.split(',')) {
+      filters.push([
+        module
+          .trim()
+          .toLowerCase()
+          .replace(/^aztec:/, ''),
+        sanitizedLevel as LogLevel | 'silent',
+      ]);
+    }
+  }
+  return filters.reverse();
+}

package/src/log/log-levels.ts

@@ -0,0 +1,3 @@
+export const LogLevels = ['silent', 'fatal', 'error', 'warn', 'info', 'verbose', 'debug', 'trace'] as const;
+
+export type LogLevel = (typeof LogLevels)[number];

package/src/log/log_fn.ts

@@ -0,0 +1,5 @@
+/** Structured log data to include with the message. */
+export type LogData = Record<string, string | number | bigint | boolean | { toString(): string } | undefined | null>;
+
+/** A callable logger instance. */
+export type LogFn = (msg: string, data?: unknown) => void;

package/src/log/noir_debug_log_util.ts

@@ -0,0 +1,21 @@
+interface Printable {
+  toString(): string;
+}
+
+/**
+ * Format a debug string filling in `'{0}'` entries with their
+ * corresponding values from the args array, amd `'{}'` with the whole array.
+ *
+ * @param formatStr - str of form `'this is a string with some entries like {0} and {1}'`
+ * @param args - array of fields to fill in the string format entries with
+ * @returns formatted string
+ */
+export function applyStringFormatting(formatStr: string, args: Printable[]): string {
+  return formatStr
+    .replace(/{(\d+)}/g, (match, index) => {
+      return typeof args[index] === 'undefined' ? match : args[index].toString();
+    })
+    .replace(/{}/g, (_match, _index) => {
+      return args.toString();
+    });
+}

package/src/log/pino-logger-server.ts

@@ -0,0 +1,25 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import { type LoggerBindings, addLogBindingsHandler, removeLogBindingsHandler } from './pino-logger.js';
+
+/** AsyncLocalStorage for logger bindings context propagation (Node.js only). */
+const bindingsStorage = new AsyncLocalStorage<LoggerBindings>();
+
+/** Returns the current bindings from AsyncLocalStorage, if any. */
+export function getBindings(): LoggerBindings | undefined {
+  return bindingsStorage.getStore();
+}
+
+/**
+ * Runs a callback within a bindings context. All loggers created within the callback
+ * will automatically inherit the bindings (actor, instanceId) via the log bindings handler.
+ */
+export async function withLoggerBindings<T>(bindings: LoggerBindings, callback: () => Promise<T>): Promise<T> {
+  const handler = () => bindingsStorage.getStore();
+  addLogBindingsHandler(handler);
+  try {
+    return await bindingsStorage.run(bindings, callback);
+  } finally {
+    removeLogBindingsHandler(handler);
+  }
+}