EIP-1193 Provider

Overview

The MiradorProvider is an EIP-1193 compatible wrapper that automatically captures transaction data for Mirador traces. It intercepts eth_sendTransaction and eth_sendRawTransaction calls, records tx hints and error data, and passes everything else through to the underlying provider. This means you can drop it into any dApp and get transaction tracing without changing your existing transaction flow.

Quick Start

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

const client = new Client('your-api-key');
const provider = new MiradorProvider(window.ethereum, client);

// Use `provider` wherever you'd use window.ethereum
// Transactions are automatically captured in Mirador traces
const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: '0xabc...',
    to: '0xdef...',
    data: '0xa9059cbb...',
    value: '0x0'
  }]
});

How It Works

Your dApp → MiradorProvider → Underlying Provider (MetaMask, etc.)
                ↓
         Mirador Trace
         ├── tx:sent event (on success)
         ├── tx:error event (on failure)
         └── TxHint with chain + input data

Your application sends a transaction through MiradorProvider
The provider intercepts eth_sendTransaction / eth_sendRawTransaction
It forwards the call to the underlying provider (e.g., MetaMask)
On success: records the tx hash as a hint and adds a tx:sent event
On failure: captures the error message, code, and revert data as a tx:error event
All other RPC methods (e.g., eth_call, eth_getBalance) pass through unchanged

Configuration

Auto-Create Traces Per Transaction

By default, MiradorProvider creates a new trace for each transaction:

const provider = new MiradorProvider(window.ethereum, client);

// Each eth_sendTransaction creates its own trace
await provider.request({ method: 'eth_sendTransaction', params: [tx1] });
await provider.request({ method: 'eth_sendTransaction', params: [tx2] });
// → 2 separate traces

You can pass traceOptions to configure the auto-created traces:

const provider = new MiradorProvider(window.ethereum, client, {
  traceOptions: {
    name: 'WalletTx',
    maxRetries: 5
  }
});

Bind to an Existing Trace

For multi-step flows where you want all transactions in a single trace:

const trace = client.trace({ name: 'CrossChainSwap' })
  .addAttributes({ user: userAddress });

const provider = new MiradorProvider(window.ethereum, client, { trace });

// All transactions go into the same trace
await provider.request({ method: 'eth_sendTransaction', params: [approveTx] });
await provider.request({ method: 'eth_sendTransaction', params: [swapTx] });
// → 1 trace with 2 tx hints

Using with Libraries

ethers.js

import { BrowserProvider } from 'ethers';
import { Client, MiradorProvider } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');
const miradorProvider = new MiradorProvider(window.ethereum, client);

// Wrap in ethers BrowserProvider
const ethersProvider = new BrowserProvider(miradorProvider);
const signer = await ethersProvider.getSigner();

// Transactions through the signer are automatically captured
const tx = await signer.sendTransaction({
  to: '0xdef...',
  value: parseEther('1.0')
});

viem

import { createWalletClient, custom } from 'viem';
import { mainnet } from 'viem/chains';
import { Client, MiradorProvider } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key');
const miradorProvider = new MiradorProvider(window.ethereum, client);

const walletClient = createWalletClient({
  chain: mainnet,
  transport: custom(miradorProvider)
});

// Transactions are automatically captured
const hash = await walletClient.sendTransaction({
  to: '0xdef...',
  value: parseEther('1.0')
});

Alternative: `sendTransaction` on Trace

If you don’t want a wrapper provider and prefer explicit control, use sendTransaction() directly on a trace. First set up the Web3Plugin, then call sendTransaction() on the trace:

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

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

const trace = client.trace({ name: 'Swap' });

const txHash = await trace.web3.evm.sendTransaction({
  from: '0xabc...',
  to: '0xdef...',
  data: '0xa9059cbb...',
  chainId: 1
});

This gives you the same automatic tx hint and error capture, but scoped to a specific trace method call.

Chain Detection

Both MiradorProvider and the Web3Plugin automatically detect the connected chain by calling eth_chainId on the underlying provider. The chain ID is mapped to a supported ChainName:

Chain ID	Chain Name
1	`ethereum`
137	`polygon`
42161	`arbitrum`
8453	`base`
10	`optimism`
56	`bsc`

You can also use the chainIdToName() utility directly:

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

chainIdToName(1);      // 'ethereum'
chainIdToName(137);    // 'polygon'
chainIdToName('0x89'); // 'polygon'
chainIdToName(999);    // undefined

Error Capture

When a transaction fails (user rejection, insufficient funds, revert, etc.), the error is automatically captured:

// This is captured automatically — no try/catch needed in your tx flow
// The trace will contain:
// {
//   event: 'tx:error',
//   details: {
//     message: 'User rejected the request',
//     code: 4001,
//     data: '0x...'  // revert data if available
//   }
// }

The original error is always re-thrown so your application’s error handling continues to work normally.

Next Steps

Transaction Hints

Learn about transaction correlation

Transaction Tracking Example

See a complete implementation

API Reference: Trace

Full method documentation

Types

EIP1193Provider, MiradorProviderOptions, etc.

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Overview

Quick Start

How It Works

Configuration

Auto-Create Traces Per Transaction

Bind to an Existing Trace

Using with Libraries

ethers.js

viem

Alternative: `sendTransaction` on Trace

Chain Detection

Error Capture

Next Steps

Transaction Hints

Transaction Tracking Example

API Reference: Trace

Types

​Overview

​Quick Start

​How It Works

​Configuration

​Auto-Create Traces Per Transaction

​Bind to an Existing Trace

​Using with Libraries

​ethers.js

​viem

​Alternative: sendTransaction on Trace

​Chain Detection

​Error Capture

​Next Steps

Transaction Hints

Transaction Tracking Example

API Reference: Trace

Types

Overview

Quick Start

How It Works

Configuration

Auto-Create Traces Per Transaction

Bind to an Existing Trace

Using with Libraries

ethers.js

viem

Alternative: `sendTransaction` on Trace

Chain Detection

Error Capture

Next Steps