Skip to main content

​
Overview

The Web3 Demo App is a fully interactive example that showcases the Mirador Web SDK end-to-end. It connects to browser wallets, sends real blockchain transactions, and tracks the entire lifecycle with Mirador traces. All code snippets below are extracted from the actual demo source code.

​
What It Demonstrates

  • Trace creation with descriptive names and structured metadata
  • Attributes for wallet, network, and transaction context
  • Tags for categorization and filtering
  • Events at each stage of the transaction lifecycle
  • Transaction hints via addTxHint() for cross-chain correlation
  • Flush to send trace data immediately
  • Error handling and trace closure on success, failure, or rejection

​
SDK Integration Walkthrough

The core SDK integration lives in a single sendTransaction() function. Here’s how it works step by step.

​
1. Initialize the Client

The client is created once when the user provides their API key: 
import { Client } from '@miradorlabs/web-sdk';

const client = new Client(apiKey, { apiUrl: 'https://ingest-gateway.mirador.org' });

​
2. Create a Trace with Metadata

When a transaction is initiated, a new trace is created and enriched with attributes and tags: 
// Create the trace
const trace = client.trace({ name: 'web3_transfer' });

// Add wallet and transaction attributes
trace
  .addAttribute('wallet.address', walletAddress)
  .addAttribute('wallet.type', 'injected')
  .addAttribute('network.name', networkInfo.name)
  .addAttribute('network.chainId', chainId.toString())
  .addAttribute('transaction.type', 'transfer')
  .addAttribute('transaction.to', recipient)
  .addAttribute('transaction.value', amount)
  .addAttribute('transaction.valueWei', amountWei.toString());

// Add tags for categorization
trace.addTags(['web3', 'transfer', 'sepolia-testnet']);

​
3. Track Events Through the Transaction Lifecycle

Events are added at each significant step, capturing relevant data: 
// When the user initiates the transaction
trace.addEvent('transaction_initiated', {
  from: walletAddress,
  to: recipient,
  value: amount,
});

// After the wallet submits the transaction
trace.addEvent('transaction_sent', { txHash });

// When the transaction confirms on-chain
trace.addEvent('transaction_confirmed', {
  success: true,
  blockNumber: 12345678,
  txHash,
});
After getting a transaction hash, link it to the trace for blockchain correlation: 
import { ChainName } from '@miradorlabs/web-sdk';

const chainName: ChainName = 'ethereum';
trace.addTxHint(txHash, chainName, 'ETH Transfer');
This enables Mirador to correlate on-chain data with your trace across any of the supported networks.

​
5. Flush and Retrieve the Trace ID

After adding the transaction hint, flush the trace to send data to Mirador and retrieve the trace ID: 
trace.flush();

// Poll for the trace ID (available after flush completes)
let traceId = trace.getTraceId();
let attempts = 0;
while (!traceId && attempts < 50) {
  await new Promise(resolve => setTimeout(resolve, 100));
  traceId = trace.getTraceId();
  attempts++;
}

​
6. Handle Errors and Close the Trace

Always close the trace when the operation completes, whether it succeeds or fails: 
// On success
trace.addEvent('transaction_confirmed', { success: true, blockNumber, txHash });
await trace.close(`Transaction confirmed in block ${blockNumber}`);

// On user rejection
trace.addEvent('transaction_rejected', { reason: 'User rejected' });
await trace.close('Transaction rejected by user');

// On error
trace.addEvent('transaction_error', { error: err.message });
await trace.close(`Transaction error: ${err.message}`);

​
Example Trace Output

When you send a transaction through the demo, the SDK captures the following data: 
{
  "name": "web3_transfer",
  "attributes": {
    "wallet.address": "0x742d...0bEb",
    "wallet.type": "injected",
    "network.name": "Sepolia Testnet",
    "network.chainId": "11155111",
    "transaction.type": "transfer",
    "transaction.to": "0x1234...7890",
    "transaction.value": "0.001",
    "transaction.valueWei": "1000000000000000"
  },
  "tags": ["web3", "transfer", "sepolia-testnet"],
  "events": [
    { "name": "trace init" },
    { "name": "transaction_initiated", "data": { "from": "0x742d...0bEb", "to": "0x1234...7890", "value": "0.001" } },
    { "name": "transaction_sent", "data": { "txHash": "0xabc...def" } },
    { "name": "transaction_confirmed", "data": { "success": true, "blockNumber": 12345678, "txHash": "0xabc...def" } }
  ],
  "txHashHints": [
    { "txHash": "0xabc...def", "chain": "ethereum", "details": "ETH Transfer" }
  ]
}

​
Supported Networks

The demo supports 12 networks (6 mainnets and 6 testnets):
NetworkChain IDSymbolMirador Chain
Ethereum1ETHethereum
Sepolia11155111ETHethereum
Polygon137MATICpolygon
Polygon Amoy80002MATICpolygon
Arbitrum One42161ETHarbitrum
Arbitrum Sepolia421614ETHarbitrum
Optimism10ETHoptimism
Optimism Sepolia11155420ETHoptimism
Base8453ETHbase
Base Sepolia84532ETHbase
BNB Chain56BNBbsc
BNB Testnet97BNBbsc

​
Running the Demo

1

Clone the repo and install dependencies

git clone https://github.com/miradorlabs/web-client.git
cd web-client/example
npm install
2

Start the development server

npm run dev
This builds the SDK, bundles the demo, starts a CORS proxy, and serves the app at http://localhost:8000.
3

Connect and send a transaction

Enter your Mirador API key, connect a browser wallet (MetaMask, Coinbase Wallet, etc.), switch to a testnet, and send a transaction to see the full trace lifecycle in action.

​
Next Steps

API Reference

Complete Client and Trace API documentation

Traces

Learn about trace lifecycle, flushing, and closing

Transaction Hints

Deep dive into cross-chain transaction correlation

Transaction Tracking

More SDK integration patterns for DeFi operations