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

# Logs & Filters

> Query event logs and create filters for monitoring

<Warning>
  **This page is a placeholder.** All examples on this page are currently AI-generated and are not correct. This documentation will be completed in the future with accurate, tested examples.
</Warning>

Query historical event logs and create filters to monitor new blocks, transactions, and events.

## Log Query

### eth\_getLogs

Query event logs matching filter criteria.

```typescript theme={null}
import { Address } from '@tevm/voltaire/Address';
import { Keccak256 } from '@tevm/voltaire/Keccak256';

const logs = await provider.eth_getLogs({
  fromBlock: 'earliest',
  toBlock: 'latest',
  address: Address('0x...'),
  topics: [Hash('0x...')]  // Event signature
});
// Response<Log[]>
```

**Parameters:**

* `fromBlock: BlockTag` - Starting block (default: 'latest')
* `toBlock: BlockTag` - Ending block (default: 'latest')
* `address?: Address | Address[]` - Contract address(es) to filter
* `topics?: Array<Hash | Hash[] | null>` - Event topic filters

**Usage patterns:**

* Query historical events from contracts
* Filter by event signature (topic\[0])
* Filter by indexed parameters (topic\[1-3])
* Search across multiple contracts

## Filter Creation

### eth\_newFilter

Create a log filter for event monitoring.

```typescript theme={null}
const filterId = await provider.eth_newFilter({
  fromBlock: 'latest',
  toBlock: 'latest',
  address: Address('0x...'),
  topics: []
});
// Response<Quantity>
```

**Parameters:** Same as `eth_getLogs`

**Returns:** Filter ID for polling

### eth\_newBlockFilter

Create a filter for new block hashes.

```typescript theme={null}
const filterId = await provider.eth_newBlockFilter();
// Response<Quantity>
```

Monitor new blocks by polling for changes.

### eth\_newPendingTransactionFilter

Create a filter for pending transaction hashes.

```typescript theme={null}
const filterId = await provider.eth_newPendingTransactionFilter();
// Response<Quantity>
```

Monitor mempool activity by polling for new transactions.

## Filter Polling

### eth\_getFilterChanges

Get new entries for a filter since last poll.

```typescript theme={null}
const changes = await provider.eth_getFilterChanges(filterId);
// Response<Log[] | Hash[]>
```

**Returns:**

* `Log[]` - For log filters
* `Hash[]` - For block/transaction filters

**Note:** Resets the filter's internal state - subsequent calls only return new changes.

### eth\_getFilterLogs

Get all logs matching a filter (does not reset state).

```typescript theme={null}
const logs = await provider.eth_getFilterLogs(filterId);
// Response<Log[]>
```

**Note:** Only works with log filters, not block/transaction filters.

## Filter Cleanup

### eth\_uninstallFilter

Remove a filter and free resources.

```typescript theme={null}
const success = await provider.eth_uninstallFilter(filterId);
// Response<boolean>
```

Always uninstall filters when done to prevent resource leaks.

## Usage Example

```typescript theme={null}
import * as Address from '@tevm/voltaire/Address';
import { Keccak256 } from '@tevm/voltaire/Keccak256';

// Create filter for Transfer events
const filterId = await provider.eth_newFilter({
  fromBlock: 'latest',
  address: Address('0x...'),
  topics: [
    Hash('0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef') // Transfer(address,address,uint256)
  ]
});

// Poll for changes
setInterval(async () => {
  const logs = await provider.eth_getFilterChanges(filterId);
  if (logs.length > 0) {
    console.log('New transfers:', logs);
  }
}, 5000);

// Cleanup on exit
process.on('exit', async () => {
  await provider.eth_uninstallFilter(filterId);
});
```

## Filter Lifecycle

1. **Create** - Use `eth_newFilter`, `eth_newBlockFilter`, or `eth_newPendingTransactionFilter`
2. **Poll** - Call `eth_getFilterChanges` periodically to get new entries
3. **Query** - Optionally use `eth_getFilterLogs` to re-query all matches
4. **Cleanup** - Call `eth_uninstallFilter` when done

<Warning>
  Filters expire after 5 minutes of inactivity on most nodes. Poll regularly to keep them alive.
</Warning>

## Related

* [State Methods](/jsonrpc-provider/eth-methods/state) - Query account and storage state
* [Transaction Methods](/jsonrpc-provider/eth-methods/transactions) - Send and query transactions
* [Block Methods](/jsonrpc-provider/eth-methods/blocks) - Query block data