Mirador Ingest Node.js SDK

Node.js SDK for the Mirador tracing platform. This package provides a server-side client using gRPC to interact with the Mirador Ingest Gateway API.

Installation

npm install @miradorlabs/nodejs-sdk

Features

• Auto-Flush - Builder methods automatically batch and send data via microtask scheduling
• Fluent Builder Pattern - Method chaining for creating traces
• Retry with Backoff - Automatic retry with exponential backoff on network failures
• Keep-Alive - Automatic periodic pings to maintain trace liveness (configurable interval)
• Trace Lifecycle - Explicit close trace method with automatic cleanup
• Blockchain Integration - Built-in support for correlating traces with blockchain transactions
• Stack Trace Capture - Automatic or manual capture of call stack for debugging
• TypeScript Support - Full type definitions included
• Multiple Transaction Hints - Support for multiple blockchain transaction correlations
• Safe Multisig Tracking - Track Safe message confirmations with addSafeMsgHint()

Quick Start

import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key');

const trace = client.trace({ name: 'SwapExecution' })
  .addAttribute('from', '0xabc...')
  .addAttribute('slippage', { bps: 50, tolerance: 'auto' })  // objects are stringified
  .addTags(['dex', 'swap'])
  .addEvent('quote_received', { provider: 'Uniswap' })
  .addEvent('transaction_signed')
  .addTxHint('0xtxhash...', 'ethereum');
// Data is auto-flushed at the end of the current JS tick.
// Call trace.close() when the trace is complete.

// ... later, when done with the trace
await trace.close('Transaction completed');

API Reference

Client

The main client for interacting with the Mirador Ingest Gateway.

Constructor

new Client(apiKey?: string, options?: ClientOptions)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | apiKey | string | No | API key for authentication (sent as x-ingest-api-key header) | | options | ClientOptions | No | Configuration options |

Options

interface ClientOptions {
  apiUrl?: string;              // Gateway URL (defaults to ingest.mirador.org:443)
  keepAliveIntervalMs?: number; // Keep-alive ping interval in milliseconds (default: 10000)
}

Methods

trace(options?)

Creates a new trace builder.

const trace = client.trace({ name: 'MyTrace' });
const trace = client.trace();  // name is optional

// Stack trace capture is enabled by default - to disable:
const trace = client.trace({ name: 'MyTrace', captureStackTrace: false });

// Configure retry behavior:
const trace = client.trace({
  name: 'MyTrace',
  maxRetries: 5,      // Override default of 3
  retryBackoff: 2000  // Override default of 1000ms
});

| Parameter | Type | Required | Description | |-----------|----------------|----------|-----------------------| | options | TraceOptions | No | Trace configuration |

interface TraceOptions {
  name?: string;             // Trace name
  captureStackTrace?: boolean; // Capture stack trace at creation (default: true)
  maxRetries?: number;       // Max retry attempts on failure (default: 3)
  retryBackoff?: number;     // Base backoff delay in ms (default: 1000)
}

Returns: Trace builder instance

Trace (Builder)

Fluent builder for constructing traces. All methods return this for chaining.

addAttribute(key, value)

Add a single attribute. Objects are automatically stringified.

trace.addAttribute('user', '0xabc...')
     .addAttribute('amount', 1.5)
     .addAttribute('config', { slippage: 50, deadline: 300 })  // stringified to JSON

addAttributes(attrs)

Add multiple attributes at once. Objects are automatically stringified.

trace.addAttributes({
  from: '0xabc...',
  to: '0xdef...',
  value: 1.0,
  metadata: { source: 'api', version: '1.0' }  // stringified to JSON
})

addTag(tag) / addTags(tags)

Add tags to categorize the trace.

trace.addTag('transaction')
     .addTags(['ethereum', 'send'])

addEvent(name, details?, options?)

Add an event with optional details (string or object) and optional settings.

trace.addEvent('wallet_connected', { wallet: 'MetaMask' })
     .addEvent('transaction_initiated')
     .addEvent('transaction_confirmed', { blockNumber: 12345 })

// With stack trace - captures where in your code the event was added
trace.addEvent('error_occurred', { code: 500 }, { captureStackTrace: true })

// Legacy: timestamp can still be passed as third parameter for backward compatibility
trace.addEvent('custom_event', 'details', new Date())

| Parameter | Type | Description | |-----------|----------------------------|-----------------------------------------------------| | name | string | Event name | | details | string \| object | Optional event details (objects are stringified) | | options | AddEventOptions \| Date | Options with captureStackTrace, or legacy Date |

addStackTrace(eventName?, additionalDetails?)

Capture and add the current stack trace as an event. Useful for debugging or tracking code paths.

trace.addStackTrace()  // Creates event named "stack_trace"
trace.addStackTrace('checkpoint', { stage: 'validation' })

| Parameter | Type | Description | |---------------------|----------|--------------------------------------------------| | eventName | string | Event name (defaults to "stack_trace") | | additionalDetails | object | Optional additional details to include |

addExistingStackTrace(stackTrace, eventName?, additionalDetails?)

Add a previously captured stack trace as an event. Useful when you need to capture a stack trace at one point but record it later.

import { captureStackTrace } from '@miradorlabs/nodejs-sdk';

// Capture stack trace now
const stack = captureStackTrace();

// ... later ...
trace.addExistingStackTrace(stack, 'deferred_location', { reason: 'async operation' })

| Parameter | Type | Description | |---------------------|--------------|--------------------------------------------------| | stackTrace | StackTrace | Previously captured stack trace | | eventName | string | Event name (defaults to "stack_trace") | | additionalDetails | object | Optional additional details to include |

addTxHint(txHash, chain, details?)

Add a transaction hash hint for blockchain correlation. Multiple hints can be added.

trace.addTxHint('0x123...', 'ethereum', 'Main transaction')
     .addTxHint('0x456...', 'polygon', 'Bridge transaction')

| Parameter | Type | Description | |-----------|------|-------------| | txHash | string | Transaction hash | | chain | ChainName | Chain name: 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc' | | details | string | Optional details about the transaction |

addSafeMsgHint(msgHint, chain, details?)

Add a Safe message hint for tracking Safe multisig message confirmations. Mirador will monitor the Safe contract for confirmation events related to the given message hash.

trace.addSafeMsgHint('0xmsgHash...', 'ethereum')
     .addSafeMsgHint('0xotherHash...', 'base', 'Token approval')

| Parameter | Type | Description | |-----------|------|-------------| | msgHint | string | The Safe message hash to track | | chain | ChainName | Chain name: 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc' | | details | string | Optional details about the message |

addTxInputData(inputData)

Add transaction input data (calldata) as a trace event. This is the hex-encoded data field from a transaction, useful for debugging failed transactions where the calldata is still available even though the transaction reverted.

trace.addTxInputData('0xa9059cbb000000000000000000000000...')

| Parameter | Type | Description | |-----------|------|-------------| | inputData | string | Hex-encoded transaction input data (calldata) |

Returns: this for chaining

flush()

Send pending data to the gateway. Fire-and-forget — returns immediately but maintains strict ordering internally.

The first flush sends CreateTrace, subsequent flushes send UpdateTrace.

trace.addEvent('important_milestone');
trace.flush();  // Send immediately

Returns: void

Note: Builder methods automatically call flush() via microtask scheduling, so you rarely need to call it manually. All synchronous builder calls within the same JS tick are batched into a single flush.

create() (deprecated)

Deprecated: Use flush() or rely on auto-flush instead. Kept for backward compatibility.

Submit the trace to the gateway synchronously and return the trace ID. Keep-alive timer starts automatically after successful creation.

const traceId = await trace.create();

Returns: Promise<string | undefined> - The trace ID if successful, undefined if failed

getTraceId()

Get the trace ID (available after first flush completes successfully, or immediately if using traceId option / setTraceId()).

const traceId = trace.getTraceId();  // string | null

Returns: string | null

close(reason?)

Close the trace and stop all timers. Flushes any pending data before sending the close request. After calling this method, all subsequent operations will be ignored.

await trace.close();
await trace.close('User completed workflow');

| Parameter | Type | Description | |-----------|------|-------------| | reason | string | Optional reason for closing the trace |

Returns: Promise<void>

Important: Once a trace is closed:

• All method calls (addAttribute, addEvent, addTag, addTxHint, addSafeMsgHint) will be ignored with a warning
• The keep-alive timer will be stopped
• Any pending data will be flushed, then a close request will be sent to the server

isClosed()

Check if the trace has been closed.

const closed = trace.isClosed();  // boolean

Returns: boolean

Complete Example: Transaction Tracking

import { Client } from '@miradorlabs/nodejs-sdk';

const client = new Client(process.env.MIRADOR_API_KEY);

async function trackSwapExecution(userAddress: string, txHash: string) {
  const trace = client.trace({ name: 'SwapExecution' })
    .addAttribute('user', userAddress)
    .addAttribute('protocol', 'uniswap-v3')
    .addAttribute('tokenIn', 'ETH')
    .addAttribute('tokenOut', 'USDC')
    .addAttribute('amountIn', '1.0')
    .addAttributes({
      slippageBps: 50,
      deadline: Math.floor(Date.now() / 1000) + 300,
    })
    .addTags(['swap', 'dex', 'ethereum'])
    .addEvent('quote_requested')
    .addEvent('quote_received', { price: 2500.50, provider: 'Uniswap' });
  // → CreateTrace auto-flushed at end of current JS tick

  try {
    await processTransaction();

    // Add more data — auto-flushed as UpdateTrace
    trace.addEvent('transaction_signed')
         .addEvent('transaction_confirmed', { blockNumber: 12345678 })
         .addTxHint(txHash, 'ethereum', 'Swap transaction');

    // Close the trace when done (flushes pending data first)
    await trace.close('Transaction completed successfully');
  } catch (error) {
    await trace.close('Transaction failed');
    throw error;
  }
}

Tracing Transaction Input Data with ethers.js / viem

When a transaction fails on-chain, the input data (calldata) still contains the encoded function call and parameters. Recording it with addTxInputData() lets you decode and debug the failure later in the Mirador dashboard.

Using ethers.js

import { Client } from '@miradorlabs/nodejs-sdk';
import { JsonRpcProvider, Wallet, parseEther } from 'ethers';

const client = new Client(process.env.MIRADOR_API_KEY);
const provider = new JsonRpcProvider(process.env.RPC_URL);
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

async function sendTracedTransaction() {
  const trace = client.trace({ name: 'ServerSwap' })
    .addAttribute('from', wallet.address)
    .addTags(['swap', 'ethereum', 'server']);

  try {
    const tx = await wallet.sendTransaction({
      to: '0xRouterAddress...',
      data: '0x38ed1739000000000000000000000000...', // encoded swap calldata
    });

    trace.addEvent('transaction_sent', { txHash: tx.hash })
         .addTxHint(tx.hash, 'ethereum')
         .addTxInputData(tx.data);  // record the calldata for debugging
    // → auto-flushed

    const receipt = await tx.wait();

    trace.addEvent('transaction_confirmed', { blockNumber: receipt.blockNumber });
    await trace.close('Swap completed');
  } catch (error) {
    trace.addEvent('transaction_failed', { error: error.message });
    await trace.close('Swap failed');
  }
}

Using viem

import { Client } from '@miradorlabs/nodejs-sdk';
import { createWalletClient, createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const client = new Client(process.env.MIRADOR_API_KEY);
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

const walletClient = createWalletClient({
  account,
  chain: mainnet,
  transport: http(process.env.RPC_URL),
});

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(process.env.RPC_URL),
});

async function sendTracedTransaction() {
  const calldata = '0xa9059cbb000000000000000000000000...' as `0x${string}`;

  const trace = client.trace({ name: 'TokenTransfer' })
    .addAttribute('from', account.address)
    .addTags(['transfer', 'ethereum']);

  try {
    const hash = await walletClient.sendTransaction({
      to: '0xTokenAddress...' as `0x${string}`,
      data: calldata,
    });

    trace.addEvent('transaction_sent', { txHash: hash })
         .addTxHint(hash, 'ethereum')
         .addTxInputData(calldata);  // record the calldata for debugging
    // → auto-flushed

    const receipt = await publicClient.waitForTransactionReceipt({ hash });

    trace.addEvent('transaction_confirmed', { blockNumber: Number(receipt.blockNumber) });
    await trace.close('Transfer completed');
  } catch (error) {
    trace.addEvent('transaction_failed', { error: error.message });
    await trace.close('Transfer failed');
  }
}

Configuration

Environment Variables

| Variable | Description | |----------|-------------| | MIRADOR_API_KEY | API key for authentication | | GRPC_BASE_URL_API | Override gateway URL |

Stack Trace Utilities

The SDK exports utilities for capturing and formatting stack traces:

import {
  captureStackTrace,
  formatStackTrace,
  formatStackTraceReadable
} from '@miradorlabs/nodejs-sdk';

// Capture current stack trace
const stack = captureStackTrace();
// stack.frames: Array of { functionName, fileName, lineNumber, columnNumber }
// stack.raw: Original Error.stack string

// Format for storage (JSON string)
const json = formatStackTrace(stack);

// Format for display (human-readable)
const readable = formatStackTraceReadable(stack);
// Output:
//   at myFunction (/path/to/file.ts:42:10)
//   at caller (/path/to/other.ts:15:5)

TypeScript Support

Full TypeScript support with exported types:

import {
  Client,
  Trace,
  ClientOptions,
  TraceOptions,      // { name?, captureStackTrace?, maxRetries?, retryBackoff? }
  AddEventOptions,   // { captureStackTrace?: boolean }
  StackFrame,        // { functionName, fileName, lineNumber, columnNumber }
  StackTrace,        // { frames: StackFrame[], raw: string }
  ChainName,         // 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bsc'
} from '@miradorlabs/nodejs-sdk';

Development

npm install          # Install dependencies
npm run build        # Build the SDK
npm run lint         # Run linter
npm test             # Run tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage

Release

npm run release:patch  # 1.0.x
npm run release:minor  # 1.x.0
npm run release:major  # x.0.0

Example CLI

An interactive CLI for testing the SDK is available in the example/ directory.

# Run the CLI
npm run cli

# Example session
mirador> create my_swap
mirador> attr user 0xabc123
mirador> tag swap
mirador> event wallet_connected '{"wallet":"MetaMask"}'
mirador> tx 0x123... ethereum
mirador> safemsg 0xabc... ethereum "Multisig approval"
mirador> flush
mirador> close "Completed"

See the example README for full documentation.

License

MIT