Migration Guide

This guide covers the v1 → v2 upgrade within the Mirador SDKs. Looking to move a backend service off @miradorlabs/nodejs-sdk and onto OpenTelemetry? See Node.js SDK (Deprecated) instead.

Overview

SDK v2 brings a plugin system, client-side trace IDs, event severity, sampling, and lifecycle callbacks. This guide covers all breaking changes and how to update your code.

Breaking Changes

1. Web3 Methods Moved to Web3Plugin

In v2, all blockchain-related methods are namespaced under a plugin. You must enable the Web3Plugin and access methods via trace.web3.*. Before (v1):

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

const client = new Client('api-key', {
  provider: window.ethereum
});

const trace = client.trace({ name: 'Swap' });
trace.addTxHint(txHash, 'ethereum');
trace.addSafeMsgHint(msgHash, 'ethereum');
trace.addSafeTxHint(safeTxHash, 'ethereum');
trace.addTxInputData(calldata);
trace.addTx(tx);
const txHash = await trace.sendTransaction(txParams);
trace.setProvider(window.ethereum);

After (v2):

import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('api-key', {
  plugins: [Web3Plugin({ provider: window.ethereum })]
});

const trace = client.trace({ name: 'Swap' });
trace.web3.evm.addTxHint(txHash, 'ethereum');
trace.web3.safe.addMsgHint(msgHash, 'ethereum');
trace.web3.safe.addTxHint(safeTxHash, 'ethereum');
trace.web3.evm.addTxInputData(calldata);
trace.web3.evm.addTx(tx);
const txHash = await trace.web3.evm.sendTransaction(txParams);
// setProvider() removed — configure via Web3Plugin

2. Client-Side Trace ID Generation

Trace IDs are now generated client-side at creation time as W3C Tracing Context compatible 32-character hex strings. They are available immediately via getTraceId() — no need to wait for the server response. setTraceId() has been removed. If you were using it to set an ID after creation, pass traceId in TraceOptions instead. Before (v1):

const trace = client.trace({ name: 'MyTrace' });
trace.flush();
// Wait for server to assign ID...
const traceId = trace.getTraceId(); // null until server responds

// Or set ID later:
trace.setTraceId(existingId);

After (v2):

const trace = client.trace({ name: 'MyTrace' });
const traceId = trace.getTraceId(); // Available immediately! 32-char hex string

// To use a specific ID, pass it at creation:
const trace = client.trace({ name: 'MyTrace', traceId: 'your-32-char-hex-id' });

3. `addEvent()` Date Parameter Removed

The legacy Date parameter for addEvent() has been removed. Use the timestamp option instead. Before (v1):

trace.addEvent('started', null, new Date('2024-01-01'));

After (v2):

trace.addEvent('started', null, { timestamp: new Date('2024-01-01') });

4. `provider` Removed from ClientOptions/TraceOptions

The provider option has been removed from both ClientOptions and TraceOptions. Use Web3Plugin instead. Before (v1):

const client = new Client('api-key', { provider: window.ethereum });
const trace = client.trace({ name: 'Swap', provider: myProvider });

After (v2):

const client = new Client('api-key', {
  plugins: [Web3Plugin({ provider: window.ethereum })]
});
// Provider is configured once via the plugin

5. Default Value Changes

Option	v1 Default	v2 Default
`maxRetries`	3	2
`retryBackoff`	1000ms	500ms

6. `create()` Method Removed

The deprecated create() method has been removed. Use flush() or rely on auto-flush. Before (v1):

const traceId = await trace.create();

After (v2):

const trace = client.trace({ name: 'MyTrace' });
const traceId = trace.getTraceId(); // Available immediately
// Or call trace.flush() to send data explicitly

New Features

Plugin System

See Plugins for full documentation.

import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('api-key', {
  plugins: [Web3Plugin({ provider: window.ethereum })]
});

Sampling

Control what percentage of traces are recorded:

const client = new Client('api-key', {
  sampleRate: 0.1  // Record 10% of traces
});

// Or use a custom sampler function
const client = new Client('api-key', {
  sampler: (name, options) => name === 'CriticalOp' ? true : Math.random() < 0.1
});

Unsampled traces return a NoopTrace that silently discards all operations.

Event Severity

Convenience methods for common severity levels:

trace.info('User logged in', { userId: 'user-123' });
trace.warn('Rate limit approaching', { remaining: 5 });
trace.error('Payment failed', { code: 'INSUFFICIENT_FUNDS' });

These are shortcuts for addEvent() with a severity field.

Lifecycle Callbacks

const client = new Client('api-key', {
  callbacks: {
    onCreated: (trace) => console.log('Trace created:', trace.getTraceId()),
    onFlushed: (trace) => console.log('Trace flushed'),
    onFlushError: (trace, error) => console.error('Flush failed:', error),
    onClosed: (trace) => console.log('Trace closed'),
    onDropped: (trace, reason) => console.warn('Trace dropped:', reason)
  }
});

Queue Management

const trace = client.trace({
  name: 'HighVolume',
  maxQueueSize: 8192,  // Default: 4096
  callbacks: {
    onDropped: (event) => console.warn('Event dropped:', event)
  }
});

Migration Checklist

Update the SDK package to v2.0: npm install @miradorlabs/web-sdk@2 (for backend services still on @miradorlabs/nodejs-sdk@2, consider moving to OpenTelemetry rather than upgrading)
Add Web3Plugin to the plugins array and move provider from ClientOptions to Web3Plugin({ provider })
Namespace all Web3 method calls: addTxHint → web3.evm.addTxHint, addSafeMsgHint → web3.safe.addMsgHint, etc.
Replace setTraceId() with traceId in TraceOptions
Replace addEvent(name, details, date) with addEvent(name, details, { timestamp: date })
Remove setProvider() calls
Remove create() calls — use auto-flush or flush()
Update retry expectations: maxRetries default is now 2, retryBackoff is now 500ms
Update CDN URLs from @1.x.x to @2.0.0

Getting Started

OpenTelemetry

Web SDK

Web3 Integration

Payments & Market Data

Automations

AI & Agents

Best Practices

Overview

Breaking Changes

1. Web3 Methods Moved to Web3Plugin

2. Client-Side Trace ID Generation

3. `addEvent()` Date Parameter Removed

4. `provider` Removed from ClientOptions/TraceOptions

5. Default Value Changes

6. `create()` Method Removed

New Features

Plugin System

Sampling

Event Severity

Lifecycle Callbacks

Queue Management

Migration Checklist

​Overview

​Breaking Changes

​1. Web3 Methods Moved to Web3Plugin

​2. Client-Side Trace ID Generation

​3. addEvent() Date Parameter Removed

​4. provider Removed from ClientOptions/TraceOptions

​5. Default Value Changes

​6. create() Method Removed

​New Features

​Plugin System

​Sampling

​Event Severity

​Lifecycle Callbacks

​Queue Management

​Migration Checklist

Overview

Breaking Changes

1. Web3 Methods Moved to Web3Plugin

2. Client-Side Trace ID Generation

3. `addEvent()` Date Parameter Removed

4. `provider` Removed from ClientOptions/TraceOptions

5. Default Value Changes

6. `create()` Method Removed

New Features

Plugin System

Sampling

Event Severity

Lifecycle Callbacks

Queue Management

Migration Checklist