Skip to main content

​
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

Optionv1 Defaultv2 Default
maxRetries32
retryBackoff1000ms500ms

​
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 SDK packages to v2.0: npm install @miradorlabs/web-sdk@2 @miradorlabs/nodejs-sdk@2
  • 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