Transaction Tracking

Overview

This example demonstrates how to use the Mirador SDK to track a complete blockchain transaction flow, from wallet connection through confirmation.

Full Example

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

// Initialize client (typically done once at app startup)
const client = new Client('your-api-key', { plugins: [Web3Plugin()] });

async function executeTokenSwap(params: {
  inputToken: string;
  outputToken: string;
  inputAmount: string;
  userAddress: string;
  slippage: number;
}) {
  // Create trace with initial context
  const trace = client.trace({ name: 'TokenSwap' })
    .addAttributes({
      inputToken: params.inputToken,
      outputToken: params.outputToken,
      inputAmount: params.inputAmount,
      userAddress: params.userAddress,
      slippage: `${params.slippage}%`
    })
    .addTags(['swap', 'dex', 'ethereum'])
    .addEvent('swap_initiated');

  try {
    // Step 1: Get quote
    trace.addEvent('fetching_quote');
    const quote = await fetchQuote(params);
    trace.addEvent('quote_received', {
      outputAmount: quote.outputAmount,
      priceImpact: quote.priceImpact,
      route: quote.route.join(' → ')
    });

    // Step 2: Check allowance and approve if needed
    const allowance = await checkAllowance(params.inputToken, params.userAddress);
    if (allowance < BigInt(params.inputAmount)) {
      trace.addEvent('approval_required');

      const approveTx = await wallet.sendTransaction(
        buildApprovalTx(params.inputToken)
      );
      trace.addEvent('approval_submitted', { txHash: approveTx.hash });
      trace.web3.evm.addTxHint(approveTx.hash, 'ethereum', 'Token approval');

      await approveTx.wait();
      trace.addEvent('approval_confirmed');
    }

    // Step 3: Execute swap
    trace.addEvent('building_swap_transaction');
    const swapTx = buildSwapTransaction(quote);

    trace.addEvent('awaiting_signature');
    const signedTx = await wallet.sendTransaction(swapTx);

    trace.addEvent('swap_submitted', {
      txHash: signedTx.hash,
      gasLimit: swapTx.gasLimit.toString()
    });
    trace.web3.evm.addTxHint(signedTx.hash, 'ethereum', 'Swap execution');

    // Step 4: Wait for confirmation
    trace.addEvent('awaiting_confirmation');
    const receipt = await signedTx.wait();

    trace.addEvent('swap_confirmed', {
      blockNumber: receipt.blockNumber,
      gasUsed: receipt.gasUsed.toString(),
      effectiveGasPrice: receipt.effectiveGasPrice.toString()
    });

    // Step 5: Verify output
    const outputBalance = await getTokenBalance(
      params.outputToken,
      params.userAddress
    );
    trace.addEvent('swap_completed', {
      outputReceived: outputBalance.toString(),
      success: true
    });

    // Close the trace when done
    await trace.close('Swap completed successfully');

    return { success: true, txHash: signedTx.hash };

  } catch (error) {
    // Record failure
    trace.addEvent('swap_failed', {
      error: error.message,
      code: error.code
    });

    // Close the trace on error
    await trace.close('Swap failed');

    return { success: false, error: error.message };
  }
}

Node.js SDK Example

The Node.js SDK uses the same auto-flush pattern. Here’s the equivalent server-side implementation:

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

const client = new Client(process.env.MIRADOR_API_KEY, { plugins: [Web3Plugin()] });

async function executeTokenSwap(params: {
  inputToken: string;
  outputToken: string;
  inputAmount: string;
  userAddress: string;
  slippage: number;
}) {
  const trace = client.trace({ name: 'TokenSwap' })
    .addAttributes({
      inputToken: params.inputToken,
      outputToken: params.outputToken,
      inputAmount: params.inputAmount,
      userAddress: params.userAddress,
      slippage: `${params.slippage}%`
    })
    .addTags(['swap', 'dex', 'ethereum'])
    .addEvent('swap_initiated');
  // → FlushTrace auto-flushed

  try {
    trace.addEvent('fetching_quote');
    const quote = await fetchQuote(params);
    trace.addEvent('quote_received', {
      outputAmount: quote.outputAmount,
      route: quote.route.join(' → ')
    });
    // → FlushTrace auto-flushed

    trace.addEvent('building_swap_transaction');
    const signedTx = await wallet.sendTransaction(buildSwapTransaction(quote));

    trace.addEvent('swap_submitted', { txHash: signedTx.hash });
    trace.web3.evm.addTxHint(signedTx.hash, 'ethereum', 'Swap execution');

    const receipt = await signedTx.wait();
    trace.addEvent('swap_confirmed', {
      blockNumber: receipt.blockNumber,
      gasUsed: receipt.gasUsed.toString()
    });

    await trace.close('Swap completed successfully');
    return { success: true, txHash: signedTx.hash };
  } catch (error) {
    trace.addEvent('swap_failed', { error: error.message });
    await trace.close('Swap failed');
    return { success: false, error: error.message };
  }
}

Step-by-Step Breakdown

1. Initialize the Trace

const trace = client.trace({ name: 'TokenSwap' })
  .addAttributes({
    inputToken: params.inputToken,
    outputToken: params.outputToken,
    inputAmount: params.inputAmount,
    userAddress: params.userAddress
  })
  .addTags(['swap', 'dex', 'ethereum']);

Start with a descriptive name and include all relevant context upfront.

2. Record Milestones

trace.addEvent('fetching_quote');
// ... async operation ...
trace.addEvent('quote_received', { outputAmount: '1000.00' });

Add events at significant points in the flow.

3. Add Transaction Hints

trace.web3.evm.addTxHint(approveTx.hash, 'ethereum', 'Token approval');
// ...
trace.web3.evm.addTxHint(swapTx.hash, 'ethereum', 'Swap execution');

Link blockchain transactions to your trace for correlation.

4. Handle Errors

catch (error) {
  trace.addEvent('swap_failed', {
    error: error.message,
    code: error.code
  });
}

Always record failures with context for debugging.

Variations

Using `sendTransaction`

Let the trace handle tx hints and error capture automatically:

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

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

async function executeSwap(params: SwapParams) {
  const trace = client.trace({ name: 'TokenSwap' })
    .addAttributes({
      inputToken: params.inputToken,
      outputToken: params.outputToken,
      userAddress: params.userAddress
    })
    .addTags(['swap', 'dex']);

  try {
    // Approval — auto-captures tx hint and errors
    if (needsApproval) {
      await trace.web3.evm.sendTransaction({
        from: params.userAddress,
        to: params.inputToken,
        data: approveCalldata,
        chainId: 1
      });
      trace.addEvent('approval_confirmed');
    }

    // Swap — auto-captures tx hint with input data
    const txHash = await trace.web3.evm.sendTransaction({
      from: params.userAddress,
      to: params.routerAddress,
      data: swapCalldata,
      chainId: 1
    });

    trace.addEvent('swap_completed', { txHash });
    await trace.close('Swap completed');
  } catch (error) {
    // tx:error already captured in the trace
    await trace.close('Swap failed');
  }
}

Using MiradorProvider

Wrap your wallet provider for zero-config transaction capture:

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

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

// Create a provider that auto-captures all transactions
const trace = client.trace({ name: 'UserSession' });
const provider = new MiradorProvider(window.ethereum, client, { trace });

// Pass to ethers, viem, or use directly — transactions are captured automatically
const txHash = await provider.request({
  method: 'eth_sendTransaction',
  params: [{
    from: userAddress,
    to: contractAddress,
    data: calldata
  }]
});

Multi-Chain Swap

const trace = client.trace({ name: 'CrossChainSwap' })
  .addTags(['swap', 'cross-chain']);

// Swap on source chain
trace.web3.evm.addTxHint(sourceTx.hash, 'ethereum', 'Source chain swap');

// Bridge transaction
trace.web3.evm.addTxHint(bridgeTx.hash, 'ethereum', 'Bridge deposit');

// Receive on destination
trace.web3.evm.addTxHint(destTx.hash, 'polygon', 'Destination receive');

Using `addTx` with Transaction Objects

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

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

const trace = client.trace({ name: 'NFTMint' })
  .addAttributes({
    collection: contractAddress,
    quantity: mintAmount,
    price: mintPrice
  })
  .addTags(['nft', 'mint']);

trace.addEvent('mint_started');

// addTx extracts hash, input data, and chain automatically
const tx = await signer.sendTransaction(mintTxData);
trace.web3.evm.addTx(tx);

const receipt = await tx.wait();
trace.addEvent('mint_confirmed', { tokenIds: mintedTokenIds });

Safe Multisig Operation

Track Safe multisig message confirmations using addSafeMsgHint():

const trace = client.trace({ name: 'SafeTransfer' })
  .addAttributes({
    safeAddress: safeAddress,
    threshold: safe.getThreshold(),
    token: tokenAddress,
    amount: transferAmount
  })
  .addTags(['safe', 'multisig', 'ethereum']);

// Propose the transaction and get the message hash
trace.addEvent('proposal_created', { nonce: safeTx.nonce });

// Track the Safe message that signers need to confirm
trace.web3.safe.addMsgHint(messageHash, 'ethereum', 'Transfer approval');

// After enough confirmations, the execution transaction is submitted
trace.web3.evm.addTxHint(executionTx.hash, 'ethereum', 'Safe execution');
trace.addEvent('transfer_executed', {
  txHash: executionTx.hash,
  signers: confirmedSigners
});

Staking Operation

const trace = client.trace({ name: 'Stake' })
  .addAttributes({
    protocol: 'lido',
    amount: stakeAmount,
    token: 'ETH'
  })
  .addTags(['stake', 'defi', 'ethereum']);

// Approval if needed
if (needsApproval) {
  trace.web3.evm.addTxHint(approveTx.hash, 'ethereum', 'Approval');
}

// Stake transaction with input data (emitted as a "Tx input data" event)
trace.web3.evm.addTxHint(stakeTx.hash, 'ethereum', {
  input: stakeTx.data,
  details: 'Stake deposit'
});
trace.addEvent('stake_confirmed', {
  stTokenReceived: receivedAmount
});

Best Practices

Add context early

Include identifying attributes (user, amounts, tokens) when creating the trace, not at the end.

Use descriptive event names

swap_submitted is better than tx_sent. Future you will thank you.

Include transaction details

Add gas used, block numbers, and other on-chain data for debugging.

Always handle errors

A trace without error handling is incomplete. Record failures with context.

Add transaction hints immediately

Don’t wait for confirmation to add the hint - add it as soon as you have the hash.

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Overview

Full Example

Node.js SDK Example

Step-by-Step Breakdown

1. Initialize the Trace

2. Record Milestones

3. Add Transaction Hints

4. Handle Errors

Variations

Using `sendTransaction`

Using MiradorProvider

Multi-Chain Swap

Using `addTx` with Transaction Objects

Safe Multisig Operation

Staking Operation

Best Practices

Next Steps

API Reference

Traces

​Overview

​Full Example

​Node.js SDK Example

​Step-by-Step Breakdown

​1. Initialize the Trace

​2. Record Milestones

​3. Add Transaction Hints

​4. Handle Errors

​Variations

​Using sendTransaction

​Using MiradorProvider

​Multi-Chain Swap

​Using addTx with Transaction Objects

​Safe Multisig Operation

​Staking Operation

​Best Practices

​Next Steps

API Reference

Traces

Overview

Full Example

Node.js SDK Example

Step-by-Step Breakdown

1. Initialize the Trace

2. Record Milestones

3. Add Transaction Hints

4. Handle Errors

Variations

Using `sendTransaction`

Using MiradorProvider

Multi-Chain Swap

Using `addTx` with Transaction Objects

Safe Multisig Operation

Staking Operation

Best Practices

Next Steps