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

# Overview

> Ethereum event log parsing, filtering, and analysis

<Card title="Try it Live" icon="play" href="https://playground.tevm.sh?example=primitives/event-log.ts">
  Run EventLog examples in the interactive playground
</Card>

<Tip>
  New to event logs? Start with [Fundamentals](/primitives/eventlog/fundamentals) for guided examples on topics, bloom filters, and ABI decoding.
</Tip>

## Type Definition

[Branded](/getting-started/branded-types) type representing an Ethereum event log with contract address, indexed topics, and event data.

```typescript theme={null}
export type EventLogType = {
  address: AddressType;
  topics: readonly HashType[];
  data: Uint8Array;
  blockNumber?: bigint;
  transactionHash?: HashType;
  transactionIndex?: number;
  blockHash?: HashType;
  logIndex?: number;
  removed?: boolean;
} & { readonly __tag: "EventLog" };
```

## API Methods

### Constructors

* [`EventLog(params)`](./from) - Primary constructor for event logs
* [`from(params)`](./from) - Alias for EventLog() constructor
* [`create(params)`](./create) - Alias for EventLog() constructor
* [`clone(log)`](./clone) - Clone existing log

### Accessors

* [`getTopic0(log)`](./getTopic0) - Get event signature (topic0)
* [`getSignature(log)`](./getSignature) - Alias for getTopic0
* [`getIndexedTopics(log)`](./getIndexedTopics) - Get all indexed topic parameters (topic1-3)
* [`getIndexed(log, index)`](./getIndexed) - Get specific indexed parameter

### Filtering

* [`matchesAddress(log, address)`](./matchesAddress) - Check if log matches contract address
* [`matchesTopics(log, topics)`](./matchesTopics) - Check if log matches topic filter
* [`matchesFilter(log, filter)`](./matchesFilter) - Check if log matches complete filter criteria
* [`filterLogs(logs, filter)`](./filterLogs) - Filter array of logs by criteria

### Utilities

* [`isRemoved(log)`](./isRemoved) - Check if log was removed due to reorg
* [`wasRemoved(log)`](./wasRemoved) - Alias for isRemoved
* [`sortLogs(logs)`](./sortLogs) - Sort logs chronologically by block and log index

## Types

<Tabs>
  <Tab title="EventLogType">
    ```typescript theme={null}
    export type EventLogType = {
      /** Contract address that emitted the log */
      address: AddressType;
      /** Event topics (topic0 = signature, topic1-3 = indexed params) */
      topics: readonly HashType[];
      /** Non-indexed event data */
      data: Uint8Array;
      /** Block number where log was emitted */
      blockNumber?: bigint;
      /** Transaction hash that generated the log */
      transactionHash?: HashType;
      /** Transaction index in block */
      transactionIndex?: number;
      /** Block hash */
      blockHash?: HashType;
      /** Log index in block */
      logIndex?: number;
      /** Log removed due to chain reorganization */
      removed?: boolean;
    } & { readonly __tag: "EventLog" };
    ```

    Main branded type with all log metadata.
  </Tab>

  <Tab title="Filter">
    ```typescript theme={null}
    export type Filter = {
      /** Single address or array of addresses (OR logic) */
      address?: AddressType | AddressType[];
      /** Topic filters (null = match any, array = OR logic) */
      topics?: readonly (HashType | HashType[] | null)[];
      /** Starting block number (inclusive) */
      fromBlock?: bigint;
      /** Ending block number (inclusive) */
      toBlock?: bigint;
      /** Specific block hash */
      blockHash?: HashType;
    };
    ```

    Filter criteria for log queries.
  </Tab>

  <Tab title="EventLogParams">
    ```typescript theme={null}
    interface EventLogParams {
      address: AddressType;
      topics: readonly (HashType | null | undefined)[];
      data: HexType;
      blockNumber?: bigint;
      blockHash?: HashType;
      transactionHash?: HashType;
      transactionIndex?: number;
      logIndex?: number;
      removed?: boolean;
    }
    ```

    Constructor parameters.
  </Tab>
</Tabs>

## Usage Patterns

### Effect Schema

```ts theme={null}
import { EventLogSchema } from '@tevm/voltaire/EventLog/effect'

// Construct from typed data
const addr = new Uint8Array(20)
const topic0 = new Uint8Array(32)
const log = EventLogSchema.from({ address: addr, topics: [topic0], data: new Uint8Array(0) })

// Filter logs
const filtered = EventLogSchema.filter([log], { address: addr })
```

### ERC-20 Transfer Event Filtering

```typescript theme={null}
import { EventLog, Address, Hash } from 'tevm';

// Transfer(address indexed from, address indexed to, uint256 value)
const TRANSFER_SIG = Hash(
  '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
);

// Filter transfers to specific user
const userAddress = Address('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2');
const userAddressHash = Hash(
  new Uint8Array([...new Uint8Array(12).fill(0), ...userAddress])
);

const transfersToUser = EventLog.filterLogs(allLogs, {
  address: usdcAddress,
  topics: [
    TRANSFER_SIG,      // Event signature
    null,              // from: any address
    userAddressHash,   // to: user
  ],
  fromBlock: 18000000n,
  toBlock: 18500000n,
});

// Sort chronologically
const sorted = EventLog.sortLogs(transfersToUser);

// Decode values
for (const log of sorted) {
  const [fromHash, toHash] = log.getIndexedTopics();
  const value = new DataView(log.data.buffer).getBigUint64(24, false);

  console.log(`Transfer: ${value} tokens`);
  console.log(`Block: ${log.blockNumber}`);
}
```

### Multi-Contract Log Parsing

```typescript theme={null}
import { EventLog, Address, Hash } from 'tevm';

const TRANSFER_SIG = Hash('0xddf252ad...');
const APPROVAL_SIG = Hash('0x8c5be1e5...');

// Monitor multiple ERC-20 tokens
const tokens = [
  Address('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'), // USDC
  Address('0x6B175474E89094C44Da98b954EedeAC495271d0F'), // DAI
  Address('0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'), // WETH
];

// Get all Transfer and Approval events
const relevantLogs = EventLog.filterLogs(allLogs, {
  address: tokens,
  topics: [[TRANSFER_SIG, APPROVAL_SIG]], // OR: either event type
});

// Process by event type
const transfers = relevantLogs.filter(log => {
  const sig = log.getTopic0();
  return sig && Hash.equals(sig, TRANSFER_SIG);
});

const approvals = relevantLogs.filter(log => {
  const sig = log.getTopic0();
  return sig && Hash.equals(sig, APPROVAL_SIG);
});

console.log(`Found ${transfers.length} transfers, ${approvals.length} approvals`);
```

### Chain Reorganization Handling

```typescript theme={null}
import { EventLog } from 'tevm';

// Filter active (non-removed) logs
const activeLogs = allLogs.filter(log => !log.isRemoved());

// Detect reorg events
const removedLogs = allLogs.filter(log => log.wasRemoved());
if (removedLogs.length > 0) {
  console.log(`Chain reorg detected: ${removedLogs.length} logs invalidated`);

  for (const log of removedLogs) {
    console.log(`  Block ${log.blockNumber}, Index ${log.logIndex}`);
  }
}

// Sort remaining logs chronologically
const sorted = EventLog.sortLogs(activeLogs);
```

### Block Range Analysis

```typescript theme={null}
import { EventLog } from 'tevm';

// Group logs by block
const byBlock = new Map<bigint, typeof allLogs>();

const sorted = EventLog.sortLogs(allLogs);
for (const log of sorted) {
  const blockNum = log.blockNumber ?? 0n;
  if (!byBlock.has(blockNum)) {
    byBlock.set(blockNum, []);
  }
  byBlock.get(blockNum)!.push(log);
}

// Analyze each block
for (const [blockNumber, blockLogs] of byBlock) {
  console.log(`\nBlock ${blockNumber}: ${blockLogs.length} logs`);

  // Count by contract
  const byContract = new Map<string, number>();
  for (const log of blockLogs) {
    const addr = Address.toHex(log.address);
    byContract.set(addr, (byContract.get(addr) || 0) + 1);
  }

  console.log('  Events per contract:', byContract);
}
```

## Bundle Size

EventLog uses optimized APIs for efficient imports and tree-shaking support.

## Related

* [EventLog (Effect)](https://voltaire-effect.tevm.sh/primitives/eventlog) - Effect.ts integration with Schema validation

### Core Documentation

* [Fundamentals](/primitives/eventlog/fundamentals) - Learn event structure, topics, and bloom filters

### Related Primitives

* [Abi](/primitives/abi) - ABI encoding/decoding for event data
* [Transaction](/primitives/transaction) - Transaction logs and receipts
* [BloomFilter](/primitives/bloomfilter) - Bloom filter for efficient log filtering
* [Address](/primitives/address) - Ethereum address handling
* [Keccak256](/crypto/keccak256) - Keccak256 hashing for event signatures

## Specification

* [Ethereum Yellow Paper](https://ethereum.github.io/yellowpaper/paper.pdf) - Section 4.3 (The Transaction Receipt)
* [EIP-155](https://eips.ethereum.org/EIPS/eip-155) - Log format specification
* [Solidity Events](https://docs.soliditylang.org/en/latest/contracts.html#events) - Event declaration and emission
* [eth\_getLogs RPC](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs) - JSON-RPC log retrieval