> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirador.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Guide

> Migrate from Mirador SDK v1 to v2

## 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):

```typescript theme={null}
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):

```typescript theme={null}
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):

```typescript theme={null}
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):

```typescript theme={null}
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):

```typescript theme={null}
trace.addEvent('started', null, new Date('2024-01-01'));
```

After (v2):

```typescript theme={null}
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):

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

After (v2):

```typescript theme={null}
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):

```typescript theme={null}
const traceId = await trace.create();
```

After (v2):

```typescript theme={null}
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](/concepts/plugins) for full documentation.

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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`