Skip to main content

​
Overview

FilterId is a branded string type representing an opaque filter identifier returned by JSON-RPC filter creation methods (eth_newFilter, eth_newBlockFilter, eth_newPendingTransactionFilter). Filter IDs are used to poll for updates and uninstall filters.

​
Type Definition

const primitives = @import("primitives");
// FilterId is a sized byte-array wrapper with len tracking
const FilterId = primitives.FilterId.FilterId;

​
Creating FilterId

​
From Hex / Bytes

const primitives = @import("primitives");
const id1 = try primitives.FilterId.fromHex("0x1");
const id2 = try primitives.FilterId.fromBytes(&[_]u8{ 0x01 });
Creates a FilterId from a string value. The string is typically a hex-encoded number returned by the node. Parameters:
  • value: string - Filter ID string
Returns: FilterIdType Throws: InvalidFilterIdError if value is not a string or is empty

​
Operations

​
Serialize for JSON

// Build JSON payloads with std.json using the hex string form when needed.
// Example payloads are shown below for each method.
Converts a FilterId back to its string representation.

​
equals

const eq = std.mem.eql(u8, id1.data[0..id1.len], id2.data[0..id2.len]);
Compares two FilterId instances for equality.

​
JSON-RPC Filter Lifecycle

Filters follow a request-response lifecycle on Ethereum nodes:

​
1. Create Filter

// {"method":"eth_newFilter","params":[{"fromBlock":"latest","address":"0x...","topics":["0x...topic0..."]}]}
// {"method":"eth_newBlockFilter","params":[]}
// {"method":"eth_newPendingTransactionFilter","params":[]}

​
2. Poll for Changes

// {"method":"eth_getFilterChanges","params":["0xFILTER_ID"]}

​
3. Get All Logs (log filters only)

// {"method":"eth_getFilterLogs","params":["0xFILTER_ID"]}

​
4. Uninstall Filter

// {"method":"eth_uninstallFilter","params":["0xFILTER_ID"]}

​
Filter Expiration

Filters automatically expire after a period of inactivity (typically 5 minutes). Nodes may:
  • Return empty arrays for expired filters
  • Return errors for invalid filter IDs
  • Silently drop old filters during node restarts
Best practices:
  • Poll filters regularly to prevent expiration
  • Handle filter not found errors gracefully
  • Recreate filters after node restarts

​
Example: Complete Filter Workflow

// 1) Create filter
// {"method":"eth_newFilter","params":[{"fromBlock":"latest","address":"0x...","topics":["0x...topic0..."]}]}

// 2) Poll changes
// {"method":"eth_getFilterChanges","params":["0xFILTER_ID"]}

// 3) Read all (log filters)
// {"method":"eth_getFilterLogs","params":["0xFILTER_ID"]}

// 4) Uninstall
// {"method":"eth_uninstallFilter","params":["0xFILTER_ID"]}

​
JSON-RPC Methods

  • eth_newFilter - Create log filter, returns FilterId
  • eth_newBlockFilter - Create block filter, returns FilterId
  • eth_newPendingTransactionFilter - Create pending tx filter, returns FilterId
  • eth_getFilterChanges - Poll for new results since last call
  • eth_getFilterLogs - Get all logs for log filter
  • eth_uninstallFilter - Remove filter from node

​
See Also