> ## 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.

# Transaction Hints

> Correlating traces with blockchain transactions

## Overview

**Transaction hints** allow you to correlate traces with blockchain transactions. When you add a transaction hash to a trace, Mirador follows the transaction wherever it goes — across bridges, through different protocols, and onto other chains — providing full end-to-end visibility from your application code to on-chain settlement.

## Adding Transaction Hints

```typescript theme={null}
trace.web3.evm.addTxHint('0x123abc...', 'ethereum');
```

<Note>
  Transaction hint methods require the `Web3Plugin`. See [Plugins](/concepts/plugins) for setup.
</Note>

### With Details

Add optional context about the transaction:

```typescript theme={null}
trace.web3.evm.addTxHint('0x123abc...', 'ethereum', 'Main swap transaction');
trace.web3.evm.addTxHint('0x456def...', 'polygon', 'Bridge to Polygon');
```

### With Input Data

Capture the transaction's calldata for deeper analysis:

```typescript theme={null}
trace.web3.evm.addTxHint('0x123abc...', 'ethereum', {
  input: '0xa9059cbb000000000000000000000000...',
  details: 'ERC-20 transfer'
});
```

<Note>
  When `input` is provided, it is emitted as a `"Tx input data"` event via `web3.evm.addTxInputData()` — it is not stored in the hint. You can also call `trace.web3.evm.addTxInputData(calldata)` directly for the same effect.
</Note>

### From a Transaction Object

Use `web3.evm.addTx()` to automatically extract the hash, input data, and chain from a transaction-like object:

```typescript theme={null}
// Works with ethers, viem, or any object with { hash, data/input, chainId }
const tx = await signer.sendTransaction(txData);
trace.web3.evm.addTx(tx);
```

## Supported Chains

| Chain    | Value        | Chain ID |
| -------- | ------------ | -------- |
| Ethereum | `'ethereum'` | 1        |
| Optimism | `'optimism'` | 10       |
| BSC      | `'bsc'`      | 56       |
| Polygon  | `'polygon'`  | 137      |
| Base     | `'base'`     | 8453     |
| Arbitrum | `'arbitrum'` | 42161    |
| HyperEVM | `'hyperevm'` | 999      |

```typescript theme={null}
import type { ChainName } from '@miradorlabs/web-sdk';

const chain: ChainName = 'ethereum';
trace.web3.evm.addTxHint(txHash, chain);
```

<Note>
  Tracking a transaction on **Solana** or **Canton**? Both live outside the
  `Chain` enum (no numeric chain ID). Use
  [`web3.solana.addTxHint(signature)`](/concepts/solana-transactions) or
  [`web3.canton.addTxHint(updateId)`](/concepts/canton-transactions) instead —
  no chain argument required.
</Note>

## Multiple Transaction Hints

A single trace can include multiple transaction hints. This is useful for complex operations that span multiple transactions. Mirador automatically follows each transaction across chains, bridges, and protocols, so you get full visibility into the entire flow:

```typescript theme={null}
const trace = client.trace({ name: 'CrossChainSwap' })
  .addEvent('swap_initiated');

// First transaction on Ethereum — Mirador follows it through the DEX
trace.web3.evm.addTxHint(ethTxHash, 'ethereum', 'Swap ETH to USDC');

// Bridge transaction — Mirador tracks it as it crosses to Polygon
trace.web3.evm.addTxHint(bridgeTxHash, 'ethereum', 'Bridge to Polygon');

// Final transaction on Polygon — full end-to-end trace across chains
trace.web3.evm.addTxHint(polygonTxHash, 'polygon', 'Receive on Polygon');
```

<Note>
  For Safe multisig message and transaction hints, see [Safe Multisig Integration](/concepts/safe-multisig).
</Note>

## Complete Example

```typescript theme={null}
import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

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

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

  try {
    // User signs transaction
    trace.addEvent('user_signing');
    const tx = await wallet.sendTransaction(swapTx);

    trace.addEvent('transaction_sent', { txHash: tx.hash });

    // Add transaction hint with input data for correlation
    trace.web3.evm.addTxHint(tx.hash, params.chain, {
      input: swapTx.data,
      details: 'Swap transaction'
    });

    // Wait for confirmation
    const receipt = await tx.wait();

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

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

### Using `sendTransaction`

For a more integrated approach, use `sendTransaction()` which automatically captures tx hints and errors:

```typescript theme={null}
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,
      inputAmount: params.amount,
    })
    .addTags(['swap', 'dex']);

  try {
    // sendTransaction handles tx hints, events, and error capture
    const txHash = await trace.web3.evm.sendTransaction({
      from: params.userAddress,
      to: params.contractAddress,
      data: params.calldata,
      chainId: 1
    });

    trace.addEvent('transaction_confirmed');
  } catch (error) {
    // Error is already captured in the trace as tx:error
    console.error('Swap failed:', error.message);
  }
}
```

## Method Signatures

### web3.evm.addTxHint

```typescript theme={null}
trace.web3.evm.addTxHint(
  txHash: string,
  chain: ChainName,
  options?: string | TxHintOptions
): Trace
```

| Parameter | Type                      | Required | Description                              |
| --------- | ------------------------- | -------- | ---------------------------------------- |
| `txHash`  | `string`                  | Yes      | The transaction hash                     |
| `chain`   | `ChainName`               | Yes      | The blockchain network                   |
| `options` | `string \| TxHintOptions` | No       | Description string or structured options |

### web3.evm.addTx

```typescript theme={null}
trace.web3.evm.addTx(tx: TransactionLike, chain?: ChainName): Trace
```

| Parameter | Type              | Required | Description                                    |
| --------- | ----------------- | -------- | ---------------------------------------------- |
| `tx`      | `TransactionLike` | Yes      | Transaction object (hash, data/input, chainId) |
| `chain`   | `ChainName`       | No       | Override chain (auto-detected if omitted)      |

### web3.evm.addTxInputData

```typescript theme={null}
trace.web3.evm.addTxInputData(inputData: string): Trace
```

| Parameter   | Type     | Required | Description                                   |
| ----------- | -------- | -------- | --------------------------------------------- |
| `inputData` | `string` | Yes      | Hex-encoded transaction input data (calldata) |

### web3.evm.sendTransaction

```typescript theme={null}
trace.web3.evm.sendTransaction(
  tx: TransactionRequest
): Promise<string>
```

| Parameter | Type                 | Required | Description            |
| --------- | -------------------- | -------- | ---------------------- |
| `tx`      | `TransactionRequest` | Yes      | Transaction parameters |

## Best Practices

### Add Hints as Soon as You Have the Hash

Don't wait for confirmation to add the hint:

```typescript theme={null}
const tx = await wallet.sendTransaction(txData);

// Add hint immediately after sending
trace.web3.evm.addTxHint(tx.hash, 'ethereum');

// Then wait for confirmation
await tx.wait();
```

### Include Descriptive Details

When dealing with multiple transactions, details help identify each one:

```typescript theme={null}
trace.web3.evm.addTxHint(approveTx, 'ethereum', 'Token approval');
trace.web3.evm.addTxHint(swapTx, 'ethereum', 'Swap execution');
```

### Match Chain to Transaction

Always use the correct chain for the transaction:

```typescript theme={null}
// Correct
trace.web3.evm.addTxHint(polygonTxHash, 'polygon');

// Incorrect - wrong chain
trace.web3.evm.addTxHint(polygonTxHash, 'ethereum');
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Solana Transactions" icon="wave-pulse" href="/concepts/solana-transactions">
    Correlate Solana transactions via signature
  </Card>

  <Card title="EIP-1193 Provider" icon="wallet" href="/concepts/provider">
    Auto-capture transactions with MiradorProvider
  </Card>

  <Card title="Traces" icon="route" href="/concepts/traces">
    Learn about trace lifecycle and flushing
  </Card>

  <Card title="Transaction Tracking Example" icon="code" href="/examples/transaction-tracking">
    See a complete implementation
  </Card>
</CardGroup>