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

# primitives/TopicFilter

> Auto-generated API documentation

[**@tevm/voltaire**](../index.mdx)

***

[@tevm/voltaire](../index.mdx) / primitives/TopicFilter

# primitives/TopicFilter

## Classes

### InvalidTopicFilterError

Defined in: [src/primitives/TopicFilter/errors.js:4](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/errors.js#L4)

Error thrown when TopicFilter is invalid

#### Extends

* `Error`

#### Constructors

##### Constructor

> **new InvalidTopicFilterError**(`message`, `details?`): [`InvalidTopicFilterError`](#invalidtopicfiltererror)

Defined in: [src/primitives/TopicFilter/errors.js:9](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/errors.js#L9)

###### Parameters

###### message

`string`

###### details?

`object`

###### Returns

[`InvalidTopicFilterError`](#invalidtopicfiltererror)

###### Overrides

`Error.constructor`

#### Properties

##### details

> **details**: `object` | `undefined`

Defined in: [src/primitives/TopicFilter/errors.js:13](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/errors.js#L13)

##### name

> **name**: `string`

Defined in: [src/primitives/TopicFilter/errors.js:11](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/errors.js#L11)

###### Inherited from

`Error.name`

## Type Aliases

### TopicEntry

> **TopicEntry** = [`HashType`](../index/namespaces/HashType.mdx#hashtype) | readonly [`HashType`](../index/namespaces/HashType.mdx#hashtype)\[] | `null`

Defined in: [src/primitives/TopicFilter/TopicFilterType.ts:7](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/TopicFilterType.ts#L7)

Single topic filter entry - either a specific hash, array of hashes (OR), or null (wildcard)

***

### TopicFilterType

> **TopicFilterType** = readonly \[[`TopicEntry`](#topicentry)?, [`TopicEntry`](#topicentry)?, [`TopicEntry`](#topicentry)?, [`TopicEntry`](#topicentry)?] & `object`

Defined in: [src/primitives/TopicFilter/TopicFilterType.ts:30](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/TopicFilterType.ts#L30)

Topic filter array for event filtering

* Up to 4 indexed event parameters (topic0, topic1, topic2, topic3)
* topic0 is typically the event signature hash
* null entries match any value (wildcard)
* Array entries match any of the values (OR logic)
* Positions use AND logic: all non-null positions must match

#### Type Declaration

##### \[brand]

> `readonly` **\[brand]**: `"TopicFilter"`

#### Example

```typescript theme={null}
// Match specific event with any sender
[eventSig, null, recipientAddr]

// Match any of multiple events
[[eventSig1, eventSig2], null, null]

// Match specific sender OR specific recipient
[eventSig, [addr1, addr2], null]
```

## Functions

### from()

> **from**(`topics`): [`TopicFilterType`](#topicfiltertype)

Defined in: [src/primitives/TopicFilter/from.js:25](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/from.js#L25)

Create TopicFilter from array

#### Parameters

##### topics

readonly \[[`TopicEntry`](#topicentry) | `undefined`, [`TopicEntry`](#topicentry) | `undefined`, [`TopicEntry`](#topicentry) | `undefined`, [`TopicEntry`](#topicentry) | `undefined`]

Topic filter array (up to 4 entries)

#### Returns

[`TopicFilterType`](#topicfiltertype)

#### Throws

#### Example

```javascript theme={null}
import * as TopicFilter from './primitives/TopicFilter/index.js';
import * as Hash from './primitives/Hash/index.js';

// Match specific event signature with any parameters
const filter1 = TopicFilter.from([Hash.from("0x...")]);

// Match specific event with specific recipient
const filter2 = TopicFilter.from([eventSig, null, recipientHash]);

// Match any of multiple events
const filter3 = TopicFilter.from([[eventSig1, eventSig2]]);
```

***

### isEmpty()

> **isEmpty**(`filter`): `boolean`

Defined in: [src/primitives/TopicFilter/isEmpty.js:12](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/isEmpty.js#L12)

Check if topic filter is empty (all wildcards)

#### Parameters

##### filter

[`TopicFilterType`](#topicfiltertype)

#### Returns

`boolean`

#### Example

```javascript theme={null}
import * as TopicFilter from './primitives/TopicFilter/index.js';
const empty = TopicFilter.isEmpty(filter); // true if all null/undefined
```

***

### matches()

> **matches**(`filter`, `logTopics`): `boolean`

Defined in: [src/primitives/TopicFilter/matches.js:19](https://github.com/evmts/voltaire/blob/bd6ec34405c15ad8cd51d11579d495dc53813482/src/primitives/TopicFilter/matches.js#L19)

Check if a topic array matches this filter

Uses AND logic across positions and OR logic within arrays:

* All non-null filter positions must match the corresponding log topic
* Array entries match if ANY of the hashes match (OR)
* null entries always match (wildcard)

#### Parameters

##### filter

[`TopicFilterType`](#topicfiltertype)

##### logTopics

readonly [`HashType`](../index/namespaces/HashType.mdx#hashtype)\[]

Topics from a log entry

#### Returns

`boolean`

#### Example

```javascript theme={null}
import * as TopicFilter from './primitives/TopicFilter/index.js';
const matches = TopicFilter.matches(filter, log.topics);
```